Skip to main content
connic

WhatsApp

Let an agent answer WhatsApp messages to your business number, photos and documents included. Replies go out from the same number, and approved templates reach people who haven't written in the last 24 hours.

Modes
Inbound, Outbound
Set up in
Dashboard or connectors/*.yaml
Documentation
WhatsApp docs
Publisher
By connic

Put an agent on your business number

Save a Connection with your Meta app and pick a phone number. When you save an inbound connector, connic sends that number's messages to the agent.

One Connection per Meta app
The Connection holds the app ID, app secret, system user token and WhatsApp Business Account ID. Every connector on it picks one phone number of that account.
Webhook set up on save
connic subscribes the app to the account and sets the callback URL of the connector's number. Other numbers keep their settings, and deleting the connector removes the callback URL.
One inbound connector per number
A number sends its messages to one inbound connector. Outbound connectors can send from the same number.
What reaches the agent
MessageWhat connic does
TextStarts a run with text
Image, audio, video, document, stickerStarts a run with files and the caption
Button and list repliesStarts a run with the title as text
Location, contactsStarts a run with raw
ReactionsIgnored
Delivery and read receiptsConnector logs

Get every message verified and ready to read

WhatsApp signs each delivery with your app secret. connic checks it, then starts every linked agent with the text, the sender and any file.

Verified deliveries
connic checks X-Hub-Signature-256 against the app secret. A message WhatsApp delivers again maps to the same run.
Files from the message
Images, audio, video, documents and stickers arrive in files, with the caption as text. Files over 32 MB are listed in file_issues.
Sender with or without a number
from holds the phone number when the person shares it. user_id identifies every sender, and replies reach both.
Conversation history
conversation_id identifies one person on one number. Set session.key to input.conversation_id, and follow-up messages share a session.
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDNBRjQ2QkZBMEM2RDQ1NjE3MjAA",
  "type": "text",
  "text": "Has order ord_8812 shipped yet?",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "name": "Jana",
  "conversation_id": "whatsapp:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091",
  "raw": { ... }
}
agents/whatsapp-support.yaml
session:
  key: input.conversation_id
  ttl: 86400

Reply within 24 hours, or send a template

Link an outbound connector with the same Connection and number. It sends after the run, when the agent calls it as a tool or when middleware calls it.

Recipient order
An explicit to comes first, then the connector's default recipient, then the person who wrote in.
Text replies
Up to 4,096 characters, within 24 hours of the person's last message.
Approved templates
Outside that window, send template with the name, language and parameters of a template Meta approved for your account.
Delivery receipts
The run output holds WhatsApp's message ID. Sent, delivered, read and failed receipts appear in the logs of the inbound connector on the same number.
reply.json
{
  "text": "Yes, ord_8812 left our warehouse today and arrives on Friday."
}
template.json
{
  "to": "+4917612345678",
  "template": {
    "name": "appointment_reminder",
    "language": "en_US",
    "parameters": ["Jana", "10:30"]
  }
}

Declare both directions in code

Declare the inbound and the outbound connector as YAML files in connectors/. Both reference the WhatsApp Connection by name, so the files hold no credentials, and each deploy creates or updates them for its environment.

connectors/support-whatsapp.yaml
type: whatsapp
mode: inbound
connection: support-whatsapp
config:
  phone_number_id: "106540352242922"
agents:
  - whatsapp-support
connectors/support-whatsapp-replies.yaml
type: whatsapp
mode: outbound
connection: support-whatsapp
config:
  phone_number_id: "106540352242922"
agents:
  - name: whatsapp-support
    outbound: { usage: automatic, source: [support-whatsapp] }

Where WhatsApp fits

Pick a setup to see what arrives from WhatsApp and what the agent sends back.

A customer sends a photo of an error message, and the agent answers with the fix.

Customer on WhatsApp
Inbound WhatsApp
product-support
Reply on WhatsApp
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDVBMjA0N0Q5RTQ2MEI3MUQ4NjAA",
  "type": "image",
  "text": "The coffee machine shows this error. What should I do?",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "conversation_id": "whatsapp:4c2a9e1b-7f3d-5b8e-a6c4-0d2f8e1a3b5c",
  "files": [
    {
      "name": "image-1184303612398871.jpg",
      "mime_type": "image/jpeg",
      "data": "<base64-bytes>",
      "size": 182344
    }
  ]
}
outbound-run-output.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABEYEjdCMjA5RjE0QzM2RDU4NEU2AA==",
  "wa_id": "4917612345678"
}

A customer asks about an order, and the agent looks it up and answers from your number.

Customer on WhatsApp
Inbound WhatsApp
order-status
Reply on WhatsApp
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDNBRjQ2QkZBMEM2RDQ1NjE3MjAA",
  "type": "text",
  "text": "Has order ord_8812 shipped yet?",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "conversation_id": "whatsapp:9e0f77d9-2fd8-5a8e-8d47-59fbf5b8a091"
}
outbound-run-output.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABEYEjFBM0Q1QzdFOUIyRjRBNkM4AA==",
  "wa_id": "4917612345678"
}

A daily schedule starts the agent, and it sends an approved template to everyone with an appointment tomorrow.

Daily schedule
Cron
appointment-reminders
Template on WhatsApp
input.json
{
  "trigger": "cron",
  "schedule": "0 7 * * *",
  "triggered_at": "2026-10-14T07:00:00",
  "prompt": "Remind every customer who has an appointment tomorrow."
}
agent-tool-payload.json
{
  "to": "+4917612345678",
  "template": {
    "name": "appointment_reminder",
    "language": "en_US",
    "parameters": ["Jana", "10:30"]
  }
}

A customer taps Reschedule on the reminder, and the agent offers free slots.

Button reply
Inbound WhatsApp
appointment-desk
Free slots on WhatsApp
input.json
{
  "message_id": "wamid.HBgNNDkxNzYxMjM0NTY3OBUCABIYFDhDMkU0QTZCOEQwRjJBNEM2RThBAA==",
  "type": "button",
  "text": "Reschedule",
  "from": "+4917612345678",
  "user_id": "US.13491208655302741918",
  "conversation_id": "whatsapp:4c2a9e1b-7f3d-5b8e-a6c4-0d2f8e1a3b5c"
}
agent-output.json
{
  "text": "No problem. Thursday 14:00 and Friday 9:30 are free. Which one suits you?"
}

WhatsApp FAQ

A Meta app with WhatsApp, a WhatsApp Business Account with a phone number, and a system user token for the app with the business_management, whatsapp_business_management and whatsapp_business_messaging permissions. You enter the app ID, app secret, token and account ID once in a Connection.

Nothing. connic sets the callback URL only for the number of the connector, so the other numbers keep sending to your app's own callback URL. If the number already has its own callback URL, saving fails instead of replacing it.

Yes, with an approved template. Link an outbound connector to an agent that a schedule, a webhook or another connector starts, and pass to and template with the message. Text replies only reach people within 24 hours of their last message.

Only with a session. Set session.key to input.conversation_id on the agent and redeploy it. Messages from the same person to the same number then share a session while it lasts.

It means WhatsApp accepted the message. WhatsApp reports later whether it reached the phone, and an inbound connector on the same number writes those receipts to its logs.