ProvidersWhatsApp
WhatsApp Business Platform numbers through your Meta app, connected with Facebook Login for Business (Embedded Signup).
The permissions each capability needs are in App Review: WhatsApp.
- There is nothing to read: the Cloud API keeps no message history and lists no conversations, so inbound messages and delivery statuses arrive only as events.
- Free-form text sends are accepted only inside WhatsApp's 24-hour customer service window.
| Content type | Operations | Events | Backfill |
|---|---|---|---|
whatsapp.dm.messages | publish | created | no |
whatsapp.dm.statuses | none | created | no |
whatsapp.dm.messages
Messages to and from the business number. Inbound messages arrive as events only: the Cloud API keeps no history.
publish
Send a WhatsApp text message from the business number to a recipient, optionally quoting one of their messages.
Submit through POST /v1/publish-requests with contentType: "whatsapp.dm.messages". These fields go in the item's args; connectedProfileId and variant are item fields.
| Field | Type | Required | Description |
|---|---|---|---|
recipientExternalId | string | yes | Provider actor the message is addressed to, such as a DM event's author.id. |
text | string | yes | Caption/body text for content. |
target | object | no | The provider content this publish targets, identified as events identify it. |
previewUrl | boolean | no | Render a link preview for the first URL in the text. |
JSON Schema
{
"additionalProperties": false,
"type": "object",
"properties": {
"recipientExternalId": {
"minLength": 1,
"description": "Provider actor the message is addressed to, such as a DM event's author.id.",
"type": "string"
},
"text": {
"description": "Caption/body text for content.",
"type": "string"
},
"target": {
"additionalProperties": false,
"description": "The provider content this publish targets, identified as events identify it.",
"type": "object",
"properties": {
"contentType": {
"const": "whatsapp.dm.messages",
"type": "string"
},
"externalId": {
"description": "Provider-owned content identifier.",
"minLength": 1,
"type": "string"
}
},
"required": [
"contentType",
"externalId"
]
},
"previewUrl": {
"description": "Render a link preview for the first URL in the text.",
"type": "boolean"
}
},
"required": [
"recipientExternalId",
"text"
]
}Not offered
list: provider no endpointget: provider no endpointupdate: provider not supportedmoderate: provider not supporteddelete: provider not supported
Events
Backfill: not offered — provider no endpoint.
Item schema
What list and get return and what events carry as data.
| Field | Type | Required | Description |
|---|---|---|---|
externalId | string | yes | Provider-owned content identifier. |
variant | "text" | "image" | "video" | "audio" | "document" | "sticker" | "location" | "contacts" | "reaction" | "interactive" | "button" | "referral" | "order" | "system" | "unsupported" | "unknown" | yes | The Cloud API message type. Media types carry media; location carries location; reaction carries reaction; unsupported is a type the Cloud API cannot deliver (e.g. a poll); unknown is a type Meta added that Koil does not model yet. |
text | string | no | Caption/body text for content. |
author | object | yes | Provider actor reference for observed content. |
thread | object | no | Parent/root identifiers for threaded contexts. |
media | object | no | |
location | object | no | Geographic place reference for content. |
reaction | object | no | |
publishedAt | string (date-time) | no | Provider publish timestamp as an ISO-8601 string. |
providerRaw | unknown | no | Optional provider-native payload included only for transient delivery/debug use. |
contentType | "whatsapp.dm.messages" | yes |
whatsapp.dm.statuses
Delivery and read statuses of messages the number sent. Events only.
Not offered
list: provider no endpointget: not applicablepublish: not applicableupdate: not applicablemoderate: not applicabledelete: not applicable
Events
Backfill: not offered — provider no endpoint.
Item schema
What list and get return and what events carry as data.
| Field | Type | Required | Description |
|---|---|---|---|
externalId | string | yes | Provider-owned content identifier. |
messageExternalId | string | yes | The outbound message this status is about. |
status | "sent" | "delivered" | "read" | "played" | "failed" | yes | The delivery state this status reports. |
recipientExternalId | string | yes | The recipient's WhatsApp id. |
occurredAt | string (date-time) | no | |
conversation | object | no | |
pricing | object | no | |
errors | object[] | no | |
callbackData | string | no | |
providerRaw | unknown | no | Optional provider-native payload included only for transient delivery/debug use. |
contentType | "whatsapp.dm.statuses" | yes |