Endpoints
The template management endpoints create, list, edit, and delete templates. The reaction endpoints return
501 resource.not_supported on WhatsApp.
Your first reply
List the conversations of your WhatsApp account:message_ids is the id that arrives on the dm.status.* events for that message, so you can follow it to delivered, read, or failed.
The 24-hour service window
WhatsApp accepts a free-form message (text, media, or interactive) only within 24 hours of the person’s most recent message to your number. Each new message from the person, including a tap on a button or list row, restarts the 24 hours.- Inside the window: send anything with
POST /v1/inbox/conversations/{conversation_id}/messages. - Outside the window: the send returns
400 whatsapp.window_closed. Send an approved template withsend-templateinstead, which WhatsApp accepts at any time.
whatsapp.window_closed still costs its interaction credit (see When a credit comes back).
Conversations and contacts
A conversation is one person writing to one connected WhatsApp number. SocialAPI creates it when the person first messages the number, or when you send them a template.
WhatsApp has no message history API, so a conversation holds only the messages sent and received after the number was connected. A number that stays on the WhatsApp Business app also brings the chat history the business chooses to share: see Keep using the WhatsApp Business app.
Contacts with a WhatsApp username
A person who uses a WhatsApp username can hide their phone number. WhatsApp then identifies them by a business-scoped user ID, a string that contains a dot, such asCO.1648230076976170, instead of a phone number. That ID is the conversation’s participant_id, the author.id on dm.received, and the recipient_id on dm.status.* events. Reply to the conversation as usual. If the person later shares their phone number, their new messages start a separate conversation.
Send a text message
POST /v1/inbox/conversations/{conversation_id}/messages sends into an existing conversation. The request fields are in Send a message. On WhatsApp:
textholds up to 4,096 characters, WhatsApp’s limit. WhatsApp rejects longer text with400 platform.whatsapp.invalid_parameter.- WhatsApp shows no link preview for a URL in
text. reply_to_message_idis ignored: the message is not shown as a reply.message_tagreturns422 messaging.tag_not_supported. Send without it.
error.meta.sent_count and error.meta.failed_index.
Send media
Add anattachments array to send images, video, audio, and documents. Each item names a url WhatsApp can fetch, or a media_id from your media library:
type, SocialAPI reads it from the file extension, and an extension that is not a known image, video, or audio extension sends a document. Set type when the extension does not match the content.
- Captions.
captionshows the text inside the media message instead of as a separate message. - Voice notes.
voice: truesends audio as a voice note. WhatsApp accepts only Ogg files encoded with the OPUS codec as voice notes.voiceon an attachment that is not audio returns400 validation.voice_unsupported. - Image formats. An image URL whose path ends in an image extension other than
.jpg,.jpeg, or.png(for example.webpor.gif) returns400 validation.image_format_unsupported. To deliver that file unchanged, send it withtype: "file". - Document names. For a
urlattachment, the document’s file name in the chat is the last segment of the URL path. - Reachability. WhatsApp downloads a
urlattachment itself, without credentials, so the URL must be public. A URL WhatsApp cannot download, or a file over its size limit, returns400 whatsapp.media_download_failed. A file WhatsApp refuses returns400 whatsapp.media_upload_failed. - Not accepted.
source_type: "platform_attachment_id"returns400 validation.attachment_id_unsupported. Stickers cannot be sent.
dm.status.failed event carries WhatsApp’s reason in error_code, error_title, and error_message.
Interactive messages
An interactive message lets the person answer by tapping instead of typing. WhatsApp offers 3 kinds, set with these fields of the send request:
Every kind needs
text, which becomes the message body, up to 1,024 characters. Missing text returns 400 validation.field_required, and longer text returns 400 validation.text_too_long. Set buttons or list_sections, not both: both return 400 validation.interactive_conflict. Interactive messages are free-form, so they need the 24-hour window.
Reply buttons
More than 3 buttons returns
400 validation.too_many_buttons.
Lists
A missing required field returns
400 validation.field_required, and a label or title over its limit returns 400 validation.title_too_long.
Link to a web page
A message with exactly 1 button oftype: "url" shows 1 button that opens url:
title is required, up to 20 characters. url is required and starts with https:// or http://. A missing title, a missing url, or a url with another scheme returns 400 validation.field_required, and a longer title returns 400 validation.title_too_long. A url button next to any other button returns 400 validation.button_type_unsupported. Opening the link sends no event.
Receive taps
A tap arrives as an ordinarydm.received event, not as a separate event type. WhatsApp posts the tapped title into the conversation as the person’s own message, so the tap also restarts the 24-hour window. The payload or row id you set is on the event’s metadata:
interactive_type is button_reply for a reply button, list_reply for a list row, or button for a quick reply button of a template. Both fields are absent on an ordinary message, so route on metadata.payload when it is present and treat the message as text otherwise.
Template messages
A template is a message Meta approved in advance. WhatsApp delivers an approved template at any time, so templates are how you message a person outside the 24-hour window, or before they have ever written to you. Sending a template does not open the 24-hour window. The window opens when the person replies, and free-form messages work from then on.Send a template
The
{account_id} in the path is the connected account ID. The sent template appears in the person’s conversation, and SocialAPI creates that conversation if the person has none. Parameters are text only: a template whose header is an image, video, or document, or whose button holds a variable, cannot be sent through this endpoint.
A template send costs 1 interaction credit and needs a paid plan. On the Free plan, send-template returns 403 whatsapp.paid_plan_required and sends nothing, and replies to people who messaged you still work. See Plans.
A name or language variant the account does not have returns 404 whatsapp.template_not_found. A template Meta paused for low quality returns 400 whatsapp.template_paused. A marketing template to a person who reached WhatsApp’s daily limit of marketing messages returns 429 whatsapp.frequency_cap. Parameters that do not match the template’s placeholders return 503 platform.whatsapp.api_error, with WhatsApp’s code in error.meta.platform_code (for example 132000 for a wrong number of parameters): fix the request before you send it again.
How many different people a number can message first in a rolling 24 hours depends on its Meta messaging tier. Read it as messaging_tier_cap from GET /v1/accounts/{account_id}/limits.
Create and manage templates
- Fields.
name,category,language, andcomponentsare required: a missing one returns400 validation.field_required.nameholds lowercase letters, digits, and underscores, up to 512 characters. A longer name returns400 validation.template_invalid.categoryisUTILITY,MARKETING, orAUTHENTICATION, and Meta can recategorize aUTILITYtemplate with marketing content asMARKETING.componentsholds exactly 1BODY(anAUTHENTICATIONtemplate can omit it), and Meta approves a component with variables only when it carries anexample. The full component schema is in the API reference. - Review. A new template is
PENDING. Meta moves it toAPPROVEDorREJECTED, and later can set it toPAUSEDorDISABLED. Read the status with the list or get endpoint before sending. - Validation. A template that breaks a rule returns
400 validation.template_invalid, with every issue inerror.meta.errors.POST /v1/platforms/whatsapp/templates/validatetakes the same body and returnsvalid,errors, andwarningswithout submitting anything. - Editing. An
APPROVED,REJECTED, orPAUSEDtemplate can be edited. A successful edit returns HTTP 204. Meta reviews the edited template again, and an editedAPPROVEDorPAUSEDtemplate returns toAPPROVEDunless it fails that review. Meta allows an approved template 1 edit per 24 hours and 10 per 30 days. - Get and edit.
GETandPUTby template ID return404 whatsapp.no_accountwhen you have no connected WhatsApp account. - Listing. Pass
paging.cursors.afterfrom one page ascursorto read the next: see Pagination.
Receive messages
Each message people send to your number appears in its conversation and arrives as adm.received event. On WhatsApp the event’s type is dm.
The table describes each message as GET /v1/inbox/conversations/{conversation_id}/messages returns it. On the dm.received event, the same values are in content.text and content.media[].type.
The
attachment_url of a received file is a SocialAPI URL that you download with your API key, not a WhatsApp URL. See Fetch an inbound attachment for the endpoint and how long the file stays available.
Delivery and read receipts
WhatsApp reports what happens to each message you send, and SocialAPI turns each report into an event and updates the message’sstatus in the conversation:
The
id on these events is the SocialAPI message ID that the send returned. The payloads are in Webhook events.
To show the person that you read their messages, or that you are typing, call POST /v1/inbox/conversations/{conversation_id}/sender-action (see Typing indicators and seen receipts). On WhatsApp:
mark_seenmarks the person’s latest message, and every earlier one, as read: they see blue ticks.typing_onshows a typing indicator and also marks the person’s latest message as read. The indicator clears when you send a message or after 25 seconds.typing_offreturns400 validation.action_unsupported: WhatsApp has none.typing_onandmark_seenneed at least 1 message from the person in the conversation. Without one, the call returns400 validation.no_inbound_message.
POST /v1/inbox/conversations/{conversation_id}/read only resets unread_count in SocialAPI: the person sees nothing. WhatsApp does not report when the person is typing.
What WhatsApp does not support
Limits
Each send and each template send costs 1 interaction credit. When the allowance is used up, the call returns
429 validation.interaction_limit_exhausted. Plans and usage lists what costs a credit.
Errors and debugging
Check these in order when a send fails:401,403 auth.insufficient_scope. The API key is invalid, or a scoped key lacksdms:send.404 conversation.not_found,404 account.not_found. The conversation does not exist, is not yours, or belongs to another connected account thanaccount_id, or the account is not one of your WhatsApp accounts.403 account.permission_missing. The connected account lacks themessages.writepermission.403 whatsapp.paid_plan_required. A template send on the Free plan.400 validation.*. The body is wrong.error.meta.fieldnames the field. The codes are in the sections above.400 whatsapp.window_closed. The 24-hour window is closed: send a template.404 whatsapp.template_not_found,400 whatsapp.template_paused. The template name, language, or status does not allow the send. A disabled template returns503 platform.whatsapp.api_errorwithplatform_code132016.400 whatsapp.undeliverable,403 whatsapp.user_opted_out. The number is not on WhatsApp, or the person opted out of your messages.400 whatsapp.media_download_failed,400 whatsapp.media_upload_failed. WhatsApp could not download or accept an attachment: see Send media.400 whatsapp.not_registered. The number is not registered for the WhatsApp Cloud API: callPOST /v1/platforms/whatsapp/phone-numbers/{account_id}/register(see Phone numbers).401 platform.whatsapp.auth,403 platform.whatsapp.permission_denied,403 account.reconnection_required. The connection is no longer authorized. Reconnect the account.429 whatsapp.pair_rate_limit,429 whatsapp.frequency_cap,429 whatsapp.throughput_exceeded,429 platform.whatsapp.rate_limit. WhatsApp refused: too many messages to this person, or from this number. These responses carry noRetry-Afterheader: retry with exponential backoff.whatsapp.pair_rate_limitandwhatsapp.frequency_capconcern 1 person, and messages to other people still go out.whatsapp.frequency_capmeans the person reached WhatsApp’s daily limit of marketing messages: send that person the template on a later day. Afterwhatsapp.throughput_exceededorplatform.whatsapp.rate_limit, further sends and other calls for the account can return429 platform.whatsapp.throttledwith aRetry-Afterheader: wait that long. See Rate limits.429 messaging.velocity_limit,429 messaging.recipient_limit, other429 messaging.*. SocialAPI’s sending limits, which apply to messages and to template sends.messaging.velocity_limitmeans the number sent too many messages in a short time.messaging.recipient_limitmeans too many different people were messaged in the current calendar day (UTC). Wait for theRetry-Afterheader. Nothing was sent and no credit was used.503 platform.whatsapp.api_error,503 whatsapp.unknown. WhatsApp refused the request for another reason, or SocialAPI got no usable answer from WhatsApp. When WhatsApp refused it,platform.whatsapp.api_errorcarries Meta’s numeric error code inerror.meta.platform_code, and Meta’s subcode inerror.meta.platform_subcodewhen Meta sent one. Withoutplatform_code, the message can still have been sent: see Create requests are not idempotent before you send it again.whatsapp.unknowncarries neither: retry it with exponential backoff.
dm.status.failed event for that message. The full list is in Errors.
Scopes
Events
SocialAPI sends these WhatsApp message events to your webhook endpoint:dm.received, dm.sent, and dm.status.sent, dm.status.delivered, dm.status.read, and dm.status.failed. dm.sent also fires for each message the business sends from the WhatsApp Business app on a number that stays on the app. An account without the messages.read permission receives no dm.received. With messages.write alone, it still receives every dm.status.* event, and dm.sent for messages sent through SocialAPI.
Use from an AI agent
No tool sends or manages templates: use the REST endpoints. See MCP tools.
Related
- WhatsApp API: connect a number, keep using the WhatsApp Business app, and the platform’s capabilities.
- Direct messages: the endpoints and fields every platform shares.
- Webhook events: the
dm.received,dm.sent, anddm.status.*payloads. - Plans and usage: template sends need a paid plan, and what costs a credit.
- Errors: every WhatsApp error code.