Speko Docs

whatsapp

WhatsApp numbers connected through your own Meta app.

speko.whatsapp connects a WhatsApp Business number through your own Meta app, so an agent answers WhatsApp calls to it. Speko reads the number from Meta with your token, then stores the token and app secret encrypted. It never returns them. The WhatsApp guide covers the Meta side.

const connection = await speko.whatsapp.connect({
  accessToken: process.env.META_SYSTEM_USER_TOKEN!,
  appSecret: process.env.META_APP_SECRET!,
  phoneNumberId: '123456789012345',
  agentId: 'agent_123',
});

// Set both on your Meta app's WhatsApp webhook, subscribed to `calls`.
console.log(connection.webhookUrl, connection.verifyToken);

Methods

MethodDescription
connect(params)POST /v1/whatsapp/connections. Takes accessToken, appSecret, phoneNumberId and an optional agentId. Returns WhatsAppConnection.
listNumbers()GET /v1/whatsapp/numbers. Returns { data: WhatsAppNumber[] }.
updateNumber(id, { agentId })PATCH /v1/whatsapp/numbers/{id}. Sets the agent that answers, or null to stop answering.
disconnect(connectionId)DELETE /v1/whatsapp/connections/{id}. Deletes the stored token and app secret and removes the number. Returns { id, revokedAt }.

WhatsAppConnection

FieldTypeDescription
idstringConnection id. Pass it to disconnect.
webhookUrlstringCallback URL for your Meta app's WhatsApp webhook.
verifyTokenstringVerify token for that webhook.
numberWhatsAppNumberThe connected number.

WhatsAppNumber

FieldTypeDescription
idstringNumber id for updateNumber.
phoneNumberIdstringMeta's phone number ID.
e164stringThe phone number.
displayNamestring | nullName Meta shows for the number.
agentIdstring | nullAgent that answers calls. null when none does.
callingStatus'enabled' | 'disabled' | 'unknown'Whether Meta lets the number take calls. Calls reach the agent only when enabled.
callingStatusCheckedAtstring | nullWhen Speko last read the status.
connection{ id, kind: 'platform' } | { id, kind: 'customer_app', webhookUrl, verifyToken }How the number reaches Speko.
createdAtstringISO timestamp.

On this page