Start agents from WhatsApp messages to your business number, and send their replies or approved templates.
On this page
| Modes | Inbound, outbound |
| YAML type | whatsapp |
| Credentials | A Connection of type whatsapp, with a Meta app and a system user token |
| Bridge | Not supported |
| Custom domain | Not supported |
| Linked agents | One or more. A message starts every linked agent. |
| Phone number | One inbound connector per number. Outbound connectors can share it. |
| While paused | Messages get 200 and start no runs. Outbound sends nothing. |
Set up
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, andwhatsapp_business_messaging.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.
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.
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.
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.
| Field | Type | Status | Description |
|---|---|---|---|
| type | string | Required | whatsapp. |
| mode | string | Required | inbound or outbound. Dashboard: Mode. |
| connection | string | Required | Inbound and outbound. Name or ID of a WhatsApp Connection. Dashboard: Connection. |
| config | object | Required | WhatsApp settings. |
| phone_number_id | string | Required | Inbound 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. |
| to | string | Optional | Outbound. 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.
| Value | Modes | Description |
|---|---|---|
| Webhook URL | Inbound | The URL connic sets as the phone number's callback URL when you save the connector. |
| Phone number | Inbound, outbound | The number's display number from WhatsApp, shown in the connector's details. |
| Verify token | Inbound, outbound | A 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:
{
"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_idis WhatsApp's ID of the message, andtypeits kind, such astext,image,document,interactive, orlocation.textis 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.fromis the sender's phone number. WhatsApp leaves it out for people who don't share their number with the business; then it'snull.user_idis the WhatsApp user ID of the sender for your business, which every message carries.nameis the sender's WhatsApp profile name, andtothe business number that received the message.conversation_idstays the same for every message from one person to the number. To give the agent the earlier messages as history, setsession.key: input.conversation_idin 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 infile_issues. rawis 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:
toin the output or payload: a phone number in E.164 format or a WhatsApp user ID.- The connector's Default recipient.
- 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.
{
"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.
{
"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
| Limit | Value |
|---|---|
| Customer service window | Text replies reach a person only within 24 hours of their last message. After that, WhatsApp delivers only approved templates. |
| Text length | 4,096 characters per message. |
| Incoming files | One 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 deliveries | WhatsApp retries a webhook that doesn't get 200 for up to 7 days. |
| Sending rate | WhatsApp 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.