Endpoints
{conversation_id} is the conversation id that GET /v1/inbox/conversations returns. Reactions and typing indicators return 501 resource.not_supported on Zalo: see What Zalo does not support.
Your first reply
List the conversations of the Zalo account:message_id is empty and each entry of message_ids is an empty string. The sent message appears in the message list with its Zalo message ID in platform_id.
Conversations
GET /v1/inbox/conversations takes the parameters described in Direct messages. Add platform=zalo to list only Zalo conversations. On Zalo:
A person with no message, sent or received, among the Official Account’s 10 most recent messages does not appear in the list until a refresh finds one. A conversation already in the list stays there. Send
POST /v1/inbox/sync with account_id to refresh the list now: see Refresh the inbox manually.
SocialAPI has no endpoint that starts a new Zalo conversation. You reply into a conversation that the list returns.
Read messages
GET /v1/inbox/conversations/{conversation_id}/messages lists the messages of a conversation, newest first.
GET /v1/inbox/conversations/{conversation_id}/messages returns up to the 10 most recent messages of the conversation (sent and received) as of the first time SocialAPI loads them, plus the messages you send through SocialAPI. That first load happens on your first read, or earlier when a POST /v1/inbox/sync with only account_id loads the conversation: see Refresh the inbox manually. A message the person sends later appears only after you send POST /v1/inbox/sync with account_id and conversation_id (1 per conversation every 5 minutes), even when its dm.received event already arrived. When more than 10 messages, sent or received, pass between two loads, the older ones that you did not send through SocialAPI never appear.
limit and cursor work as on every platform: see Pagination.
Send a message
POST /v1/inbox/conversations/{conversation_id}/messages sends a message to the person. Every message goes out as a Zalo consultation message, the message type Zalo reserves for answering a person who contacted the OA. SocialAPI sends text first, then each attachment in order, as separate messages. The request costs 1 interaction credit however many messages it sends.
The fields are described in Send a message. On Zalo:
SocialAPI does not apply the Instagram and Facebook limits on interactive content to Zalo, and it does not refuse
buttons together with cards. Zalo does not document buttons on a contact card.
Attachments
Thetype of an attachment decides what Zalo receives:
Files and uploaded-image IDs come from Zalo’s upload API, which needs the Official Account’s access token. SocialAPI does not expose that token or an upload endpoint, so you cannot send a file through SocialAPI. Stickers sent as
platform_attachment_id work, because their IDs come from Zalo’s public sticker catalog.
Buttons
buttons attaches buttons to the message, which shows text as its body.
Zalo accepts at most 5 buttons per message, and shows them only in the Zalo mobile app. SocialAPI sends no
dm.postback event for a tap on a Zalo button. A tap on a postback button counts as an interaction with the OA, so it reopens the 7-day messaging window.
Contact request card
On Zalo, the first entry ofcards becomes a card that asks the person to share their contact information with the OA. SocialAPI sends no event when the person shares it.
Every entry of
cards after the first is ignored.
The 7-day messaging window
Zalo lets an Official Account send a consultation message only to a person who interacted with the OA within the last 7 days and has not blocked it. Zalo counts these actions by the person as interactions:- Sending a message to the OA
- Following the OA
- Tapping Message on the OA’s profile
- Calling the OA, or accepting a call from it
- Commenting on one of the OA’s posts
- Tapping a menu entry or a
postbackbutton that sends a message to the OA
422 platform.zalo.not_deliverable. error.meta.zalo_code holds Zalo’s numeric reason code:
The refused send still costs 1 interaction credit. To avoid it, compare the time of the person’s latest
dm.received event with the 7-day window before you send. The message list can lag behind that event, so its created_at values are a weaker signal. Only text messages raise the event, so a person who interacted in another way can still be reachable. The person’s next interaction reopens the window.
What Zalo does not support
- Reactions.
POST /v1/inbox/conversations/{conversation_id}/messages/{message_id}/reactionandDELETEon the same path return501 resource.not_supported. - Typing indicators and seen receipts.
POST /v1/inbox/conversations/{conversation_id}/sender-actionreturns501 resource.not_supported. - Promotion, transaction, and broadcast messages. SocialAPI sends consultation messages only, so you cannot message a person outside the 7-day window.
- Message tags.
message_tagreturns422 messaging.tag_not_supported. - Quick replies and list menus.
quick_repliesandlist_sectionsare ignored. - Delivery and read status. A message you send keeps
status: "pending", and SocialAPI sends nodm.sentordm.status.*event for Zalo.
Limits
Zalo also limits requests per minute for each app and each Official Account, sets usage quotas per feature, and limits how many messages one person can receive from the OA. When a limit is reached, the call fails with
429 platform.zalo.rate_limit and no Retry-After header: wait at least 60 seconds, then retry with exponential backoff. See Platform limits. A refused send costs 1 interaction credit. When retries with exponential backoff keep returning it, stop: the Official Account’s or the person’s quota is used up.
Errors and debugging
Check these in order when a Zalo call fails:403 auth.insufficient_scope,403 account.permission_missing,403 account.reconnection_required,404 account.not_found,404 conversation.not_found. A scoped key lacks the scope the call needs (dms:readto list, get, or sync,dms:sendto send), the account lacks the permission the call needs (messages.writeto send,messages.readto start or read an inbox sync), needs reconnecting, does not exist, or does not own the conversation. See Errors and debugging.400 validation.*,422 messaging.tag_not_supported. The body is wrong, or it setsmessage_tag.error.meta.fieldnames a wrong field.422 platform.zalo.not_deliverable. The messaging window is closed, or Zalo does not let the OA reach the person. Readerror.meta.zalo_code: see The 7-day messaging window.400 validation.platform_param. Zalo rejected a parameter, for example an image it cannot read.error.messagecarries Zalo’s reason. When the first message of the request fails this way, the credit comes back.401 platform.zalo.auth. The access token expired or was revoked, or the OA no longer authorizes SocialAPI’s app. Reconnect the account. Until you do, calls return401 platform.zalo.author403 account.reconnection_required.404 resource.not_found. Zalo reports that the Official Account was deleted or does not exist.429 validation.interaction_limit_exhausted,429 platform.zalo.rate_limit. Your plan’s interaction allowance is used up, or a Zalo limit is reached: see Limits.503 platform.zalo.e<N>,503 platform.zalo.api_error. Zalo returned an error SocialAPI does not map (<N>is the absolute value of Zalo’s numeric code), or the request failed before Zalo answered.501 resource.not_supported. You called the reaction or sender action endpoint.429 inbox.sync_rate_limited.POST /v1/inbox/syncran again for the same target before its wait ended. Wait forRetry-After: see Refresh the inbox manually.
error.meta.sent_count and error.meta.failed_index say where to resume. The full catalog is in Errors.
Scopes
The account also needs the
messages.read and messages.write permissions.
Events
Zalo sends SocialAPI a person’s text messages as they happen, and SocialAPI delivers each one to your webhook endpoints asdm.received:
author.id is the person’s Zalo user ID, the participant_id of their conversation. The event has no author.name, no conversation_id, and no platform_id. To find the conversation, list conversations with account_id and match participant_id. If no conversation matches, send POST /v1/inbox/sync with account_id, wait until state is no longer syncing, then list again. raw_payload is the event as Zalo sent it.
Only text messages raise an event. Images, files, stickers, audio, video, locations, links, business cards, follows, taps on Message on the OA’s profile, reactions, read receipts, and messages the OA sends raise none. An account without the messages.read permission receives no dm.received. Every payload is on Webhook events.
Use from an AI agent
social_api_send_sender_action returns resource.not_supported on Zalo. See MCP tools.
Related
- Zalo API: capabilities, connecting an Official Account, and scopes
- Zalo publishing: publish and delete OA articles
- Direct messages: the request fields every platform shares
- Unified inbox: refresh conversations and messages on demand
- Webhook events: the
dm.receivedpayload - Plans and usage: what costs an interaction credit