Skip to main content
connic
Connectors

WhatsApp

Start agents from WhatsApp messages to your business number, and send their replies or approved templates.

Last updated
ModesInbound, outbound
YAML typewhatsapp
CredentialsA Connection of type whatsapp, with a Meta app and a system user token
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A message starts every linked agent.
Phone numberOne inbound connector per number. Outbound connectors can share it.
While pausedMessages get 200 and start no runs. Outbound sends nothing.

Set up

  1. In Meta Business Settings, open Users → System users and add a system user. Under Assign assets, give it full control of your Meta app and access to the WhatsApp Business Account. Click Generate token, select the app, and grant business_management, whatsapp_business_management, and whatsapp_business_messaging.

  2. In the Meta App Dashboard, copy the App ID and App secret from App settings → Basic. On the app's WhatsApp → API Setup page, copy the WhatsApp Business Account ID and the Phone number ID of the number your agents use.

  3. In connic, open Project Settings → Connections, click New connection, and choose WhatsApp. You can also create the Connection from the Connection picker in the connector form. Enter a Name, the App ID, App secret, Access token, and WhatsApp Business Account ID, and click Create connection.

  4. Open the agent. In Connector Flow, click Add inbound connector for incoming messages or Add outbound connector for replies. Then click Create New Connector and choose WhatsApp.

  5. Choose the mode, Inbound (Incoming messages) or Outbound (Send messages), pick the Connection under Connection, and enter the Phone number ID. Click Create. An inbound connector sets up the number's webhook now; see Phone number webhook. For outbound, then choose how the agent uses the connector and click Link connector.

Configuration

The fields of a WhatsApp connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.

FieldTypeStatusDescription
typestringRequiredwhatsapp.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredInbound and outbound. Name or ID of a WhatsApp Connection. Dashboard: Connection.
configobjectRequiredWhatsApp settings.
phone_number_idstringRequiredInbound and outbound. The ID of a phone number in the Connection's WhatsApp Business Account. Inbound connectors receive its messages; outbound connectors send from it. Dashboard: Phone number ID.
tostringOptionalOutbound. A phone number in E.164 format, such as +4915112345678, that every message goes to. Without it, replies go to the person whose message started the run. Dashboard: Default recipient.

The app ID, app secret, access token, and WhatsApp Business Account ID belong to the Connection, not to the connector.

Generated values

connic sets these when you save the connector or its Connection.

ValueModesDescription
Webhook URLInboundThe URL connic sets as the phone number's callback URL when you save the connector.
Phone numberInbound, outboundThe number's display number from WhatsApp, shown in the connector's details.
Verify tokenInbound, outboundA random token stored on the Connection. WhatsApp sends it back when it checks the webhook URL.

Agent input

Modes: Inbound

An inbound connector starts a run for every linked agent each time someone sends a message to its phone number. The run receives:

payload.json
{
  "message_id": "wamid.HBgNNDkxNTExMjM0NTY3OBUCABIYFDNBRjQ2QkZBMEM2RDQ1NjE3MjAA",
  "type": "text",
  "text": "Hi, where is my order 4711?",
  "from": "+4915112345678",
  "user_id": "US.13491208655302741918",
  "name": "Jane Doe",
  "to": "4930123456789",
  "conversation_id": "whatsapp:5f0c2a9e-1b7d-5c3a-9e2f-7a4b6d8c0e13",
  "raw": { ... }
}
  • message_id is WhatsApp's ID of the message, and type its kind, such as text, image, document, interactive, or location.
  • text is the message text, the caption of a file, or the title of the button or list item the person tapped. It's empty for other kinds.
  • from is the sender's phone number. WhatsApp leaves it out for people who don't share their number with the business; then it's null. user_id is the WhatsApp user ID of the sender for your business, which every message carries.
  • name is the sender's WhatsApp profile name, and to the business number that received the message.
  • conversation_id stays the same for every message from one person to the number. To give the agent the earlier messages as history, set session.key: input.conversation_id in its YAML; the connector doesn't turn on sessions by itself.
  • Images, audio, video, documents, and stickers arrive in files. A file that couldn't be added is listed in file_issues.
  • raw is the message as WhatsApp sent it.

Reactions and messages WhatsApp marks as unsupported start no runs. A message WhatsApp delivers again doesn't start another run. Sent, delivered, read, and failed receipts for outgoing messages appear in the connector's logs. Inbound mode doesn't reply by itself: link the agent to an outbound WhatsApp connector that uses the same Connection and phone number; see Outbound delivery.

Phone number webhook

Modes: Inbound

Saving an inbound connector subscribes the Connection's app to the WhatsApp Business Account, if it isn't yet, and sets the connector's webhook URL as the callback URL of its phone number. Only that number's messages come to connic; other numbers in the account keep sending to the app's own callback URL. Deleting the connector removes the number's callback URL again.

connic checks the signature of every delivery with the app secret. Saving fails when the number already has a callback URL of its own, so connic never replaces another system's webhook. Remove that callback URL in Meta first.

Outbound delivery

Modes: Outbound

An outbound WhatsApp connector sends one message from its phone number each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The first rule that applies decides the recipient:

  1. to in the output or payload: a phone number in E.164 format or a WhatsApp user ID.
  2. The connector's Default recipient.
  3. The person whose message started the run, when an inbound WhatsApp connector on the same Connection and phone number received it.

Automatic output

An automatic link sends the run's final output. Plain text becomes the message. A JSON object takes the text from text, body, message, response, or output, in that order, and can set to.

output.json
{
  "text": "Your order 4711 left our warehouse today and arrives on Friday."
}

Templates

More than 24 hours after a person's last message, and for anyone who hasn't written yet, WhatsApp only delivers templates that Meta approved for your account. Set template instead of text, with the template's name, its language code, and its parameters: a list of strings for numbered parameters, or an object for named ones.

output.json
{
  "to": "+4915112345678",
  "template": {
    "name": "order_update",
    "language": "en_US",
    "parameters": ["Jane", "4711"]
  }
}

Agent-tool and middleware payload

The model or middleware passes text or template, and optionally to, in the same form as the output above. Other fields are rejected.

Delivery and retries

When WhatsApp rate-limits a message, connic waits and sends it again. The connector's runs show each message with WhatsApp's message ID, or with the error. WhatsApp reports whether a message reached the phone later, in the receipts an inbound connector on the same number logs.

Limits and errors

LimitValue
Customer service windowText replies reach a person only within 24 hours of their last message. After that, WhatsApp delivers only approved templates.
Text length4,096 characters per message.
Incoming filesOne file per message, up to 32 MB in the run input. WhatsApp itself accepts images up to 5 MB, audio and video up to 16 MB, and documents up to 100 MB; larger files are listed in file_issues.
Failed deliveriesWhatsApp retries a webhook that doesn't get 200 for up to 7 days.
Sending rateWhatsApp limits messages per number, per account and per recipient. When it rate-limits, connic waits and sends again.

Requests with a missing or wrong signature get 401. Saving a connector fails when the access token or app secret is wrong, when the phone number isn't in the WhatsApp Business Account, and for inbound connectors when the number already has its own callback URL or belongs to another connic connector. A message fails when WhatsApp rejects it, for example text sent outside the 24-hour window or a template that isn't approved.