WhatsApp messaging

A WhatsApp number answered by a text agent takes three things: a sender registered at your BSP (Twilio or Gupshup), a whatsapp integration holding its credential, and a whatsapp.message.inbound trigger pointing at a published text agent. The same integration sends template batches and, on Twilio, takes WhatsApp calls. Talqing does not register senders or create templates; do both at your BSP. Your BSP and Meta bill you for WhatsApp traffic; Talqing charges its per-message platform fee when the agent answers.

Set it up

Connect the number

In WhatsApp → Numbers, press Connect number.

Twilio — the Account SID and the account’s Auth Token (not an API key: Twilio signs its webhooks with the Auth Token). Find numbers lists the account’s senders (POST /v1/whatsapp/twilio-senders); only ONLINE senders can be picked. Each becomes its own integration.
Gupshup — the app ID, the app name exactly as Gupshup shows it, an API key from the app’s Settings → API Keys, and the WhatsApp number.

The connection is checked live before it is saved: Twilio must list the sender as ONLINE, and Gupshup must accept the key for that app. The credential is stored as a workspace secret.

curl -X POST https://api.talqing.com/v1/integrations \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Sales WhatsApp",
    "provider": "whatsapp",
    "credentials_ref": "{{secrets.TWILIO_AUTH_TOKEN}}",
    "provider_account_info": {
      "bsp": "twilio",
      "account_sid": "AC0123456789abcdef0123456789abcdef",
      "sender_e164": "+14155550100"
    }
  }'

For Gupshup, credentials_ref is the API key and provider_account_info is {"bsp": "gupshup", "app_id": "…", "app_name": "AcmeSupport", "sender_e164": "+919876543210"}.One number is one integration; a second connection for the same number is refused. The number cannot be changed later — connect the other number instead. Rotate the credential with a PATCH of credentials_ref.

Choose who answers messages

Pick a published text agent in the number’s Messages cell, or create the trigger over the API:

curl -X POST "https://api.talqing.com/v1/integrations/$INTEGRATION_ID/triggers" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trigger_type": "whatsapp.message.inbound",
    "agent_id": "9f1c0a3e-4b21-4f7a-9c6d-2a5b8e13d704",
    "enabled": true
  }'

Enabling registers Talqing’s webhook with the BSP. On Twilio it replaces any URL set on that sender. On Gupshup it appears in the app’s Webhooks tab as talqing-<integration id>; leave it there. Disabling the trigger, or disabling or deleting the integration, removes it.

Message the number

Send the number a WhatsApp message. On Twilio you see a typing indicator (Gupshup has none), then the reply. The thread appears under Conversations with surface whatsapp.

Using a number from another carrier

Twilio registers any number you own as a WhatsApp sender, including one rented from a carrier such as Plivo; the carrier keeps its phone calls and Twilio carries WhatsApp. Meta verifies the number with a code by SMS or voice call, so if the number already answers calls through a Talqing agent, forward it to a phone you can answer while you register, then put it back (Run setup again on the number in Telephony → Phone Numbers). A message sent before the new sender is ONLINE fails with Twilio 63007. On a number that does both, a person is one contact whether they call it or message it on WhatsApp — see below.

What the agent knows

The contact key is phone:<your number>:<their number> — the same contact their phone calls and WhatsApp calls to that number use, with one userdata. Someone who hides their number on WhatsApp is whatsapp:<your number>:<their WhatsApp id>.

Variable	Value
`{{system_vars.human_phone_number}}`	Their number, E.164 (absent if they hide it)
`{{system_vars.agent_phone_number}}`	Your WhatsApp number
`{{system_vars.direction}}`	`inbound` — they wrote first; `outbound` on a chat an instruction opened
`{{system_vars.channel}}`	`whatsapp_message`
`{{userdata.whatsapp.phone}}`	The customer’s number, E.164
`{{userdata.whatsapp.profile_name}}`	Their WhatsApp profile name, when WhatsApp sends one

Their 24-hour WhatsApp window — when free-form messages are allowed — is on the conversation’s contact as ref.whatsapp_window_expires_at. Any message or call from them refreshes it, answered or not. Someone who first heard from you through a batch also carries that row’s columns as {{userdata.<column>}}, and the template sits in the thread as the agent’s first message. The same goes for a template or message you posted with userdata: a chat their reply starts begins from the userdata of everything posted since the thread’s last session, so even an agent on context: none knows what the send carried. To message someone yourself — a template, text as the agent, a note for the agent, or an instruction it acts on — see posting into a conversation.

One chat until it ends

All of a person’s messages join one chat. It ends when the agent runs end_call, you call POST /v1/chats/{id}/end, or 24 hours pass without a message from them (inactivity_timeout); their next message starts a new chat, in a new conversation unless the agent’s conversation.context is transcript. Analysis and session.completed happen when a chat ends, so give the agent an end_call tool. On an inactivity_timeout WhatsApp’s 24-hour window has usually closed, so a message the agent’s on_exit hook sends is not delivered (it is recorded as failed); the hook’s tools and userdata changes still run.

A reply to a template joins the template’s conversation, whatever context says.
Switching the Messages agent ends the chats it opened (close_reason: "replaced") at once; the new agent answers their next message in a new chat. Turning Messages off ends every open chat (messages_off).
A post or batch can choose the agent instead; that chat keeps running whatever Messages is switched to.
A message to a number with no agent on Messages, and none chosen for them, is stored in the thread and starts no chat.
{{vars.*}}, secrets, overrides and labels come from the post that chose the agent, or else from your inbound webhook, asked once when a chat opens, for an agent that turns it on; otherwise the agent runs on its declared defaults.

What is delivered

What reaches the agent:

They send	The agent reads	On the item
Text	The text	`text`
A quick-reply button tap	The button’s text, as if typed	`content`: `{kind: "button", button: {text, payload}, replied_to}`
Photos, with or without a caption	The photos if the model has `vision: true`, otherwise a line asking them to describe it; then the caption	`attachments` — see images
A PDF or Word (`.docx`) file	Its text, and a PDF’s scanned pages as images when the model has `vision: true`	`attachments` — see documents
A voice note or audio file	What was said, when the agent has a speech-to-text model; otherwise a line asking them to type it	`attachments`: `kind: "audio"`, with `transcript` once transcribed
A shared contact	The name, phone numbers, emails and organization on each card	`attachments`: `kind: "contact"`, with `contacts` and the `.vcf`
A video, spreadsheet or any other file	A line saying it arrived and that it cannot open it, then the caption	`attachments`: you can play a video, and download anything else
A file that could not be received (over 20 MB, or the download failed)	A line saying so, asking them to send it again	`attachments_not_kept`

A button’s payload is what you attached to it in the template; it is stored for your systems and never shown to the agent. replied_to is the provider_message_id of the template message the tap answers. Up to 4 files per message are kept. Buttons, files and captions are read on Twilio senders; Gupshup reads plain text only and drops everything else. Every stored file also fires conversation.attachment.received as soon as it is stored, with a link to download it. Replies are text. One longer than 4,096 characters is split at the last line or word break and sent in order. WhatsApp lets a business send free-form messages only within 24 hours of the customer’s last message. A reply is always inside that window; starting a conversation takes an approved template, which is what batches send.

`reply_mode`

Value	On WhatsApp
`public_reply`	The reply is sent. Default
`none`	The agent runs and its reply is recorded, but nothing is sent
`internal_note`	Not usable: WhatsApp has no private notes; the item settles `skipped`

When something fails

What you see	Why
`400` on connect: `… is not a WhatsApp sender on Twilio account …`	The number is not a sender on that account
`400` on connect: `Twilio reports sender … as OFFLINE`	New senders go offline briefly after registration. Retry in a few minutes
`400` on connect: `Gupshup rejected the API key …`	Create a new key on the app’s Settings → API Keys
Trigger `error`: `could not point the Twilio sender at Talqing: …`	Twilio refused the webhook update. Fix the cause and enable again
Trigger `error`: `could not register Talqing's webhook with Gupshup: …`	Gupshup refused the subscription. Fix the cause and enable again
A reply marked `failed` with `63016`	Outside the 24-hour window
Message marked with an error, chat closed as Your inbound webhook did not answer	The agent asks your inbound webhook and it failed; nothing was sent, and their next message asks again

WhatsApp calls

Answer calls to a Twilio number with a voice agent.

Creating a batch

Start conversations with an approved template.

Get started

Build

Guides

WhatsApp messaging

Set it up

Using a number from another carrier

What the agent knows

One chat until it ends

What is delivered

`reply_mode`

When something fails

Next

WhatsApp calls

Creating a batch

​Set it up

​Using a number from another carrier

​What the agent knows

​One chat until it ends

​What is delivered

​reply_mode

​When something fails

​Next

WhatsApp calls

Creating a batch

Set it up

Using a number from another carrier

What the agent knows

One chat until it ends

What is delivered

`reply_mode`

When something fails

Next