Apariencia
Referencia: Mensajes
Generada desde el contrato OpenAPI
Esta referencia se genera directamente del contrato de la API, por lo que sus descripciones están en inglés. Puedes descargarlo en openapi.json. Las guías explican cómo usar estos endpoints.
List messages
GET
/messages
Inbound and outbound messages, newest first, with cursor pagination (follow meta.next_cursor). For the history of one conversation, filter by phone (a direct chat, both directions) or group, optionally within since/until. A number linked by QR brings its last 30 days of chats; older messages of a chat can be asked with POST /messages/history.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Parámetros
Query Parameters
instance
Only messages of this instance.
Tipo
string
Longitud máx.
40direction
Tipo
string
Valores válidos
"outbound""inbound"type
Tipo
string
Valores válidos
"text""image""document""audio""video""sticker""location""contact""poll""unsupported"status
One status or a comma-separated list of statuses.
Tipo
string
Longitud máx.
120limit
Page size (default 25).
Tipo
integer
Mínimo
1Máximo
100cursor
Opaque cursor from a previous page (meta.next_cursor).
Tipo
string
Longitud máx.
512phone
Only the direct chat with this number, in both directions (group messages are not included). International format, country code + number (+52 55 0000 0000, 5215500000000). For Mexican mobiles both 52 + 10 digits and 521 + 10 digits match the same chat. Not with group.
Tipo
string
Ejemplo
"+5215500000000"Longitud máx.
32group
Only the messages of this group (grp_…). Not with phone.
Tipo
string
Longitud máx.
40since
Only messages that entered ZAPPIO at or after this moment. ISO 8601 (without a time zone, UTC) or a Unix timestamp in seconds.
Tipo
string
Ejemplo
"2026-11-01T00:00:00-06:00"Longitud máx.
40until
Only messages that entered ZAPPIO at or before this moment. ISO 8601 or a Unix timestamp in seconds. Not before since.
Tipo
string
Longitud máx.
40Respuestas
A page of messages.
application/json
JSON "data": [ { "id": "string", "instance_id": "string", "direction": "string", "from_me": true, "source": "string", "api_key_id": "string", "from_name": "string", "type": "string", "status": "string", "to": "string", "from": "string", "group_id": "string", "text": "string", "caption": "string", "media": { "mime_type": "string", "size": 0, "filename": "string", "available": true }, "location": { "latitude": 0, "longitude": 0, "name": "string", "address": "string", "url": "string", "live": true }, "contacts": [ ], "poll": { "question": "string", "multiple": true, "options": [ { "name": "string", "votes": 0 } ], "voters": 0, "votes": [ { "from": "string", "from_me": true, "options": [ "string" ], "voted_at": "string" } ], "votes_available": true }, "reply_to": "string", "forwarded": true, "reactions": [ { "emoji": "string", "from": "string", "from_me": true, "reacted_at": "string" } ], "error": { "code": "string", "message": "string" }, "created_at": "string", "queued_at": "string", "sent_at": "string", "delivered_at": "string", "read_at": "string", "failed_at": "string", "received_at": "string", "edited_at": "string", "deleted_at": "string" } ], "links": { "additionalProperties": "string" }, "meta": { "per_page": 0, "next_cursor": "string", "prev_cursor": "string", "additionalProperties": "string" }
{
}
GET
/messages
Ejemplos
Send a message
POST
/messages
Queues a message to a phone number or a group - text, media (image, document, audio, video, sticker), a location, shared contacts or a poll. Sending is asynchronous - the response is 202 with status queued; follow the status through GET /messages/{message} or the message.* webhooks. Use JSON for text, location, contact and poll, and multipart/form-data for media. Send an Idempotency-Key to make retries safe. Messages of type unsupported (received content ZAPPIO does not read) cannot be sent.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Parámetros
Header Parameters
Idempotency-Key
1 to 255 printable ASCII characters, no spaces. Keys are remembered for 24 hours. The same key with the same request returns the original message (200 and Idempotent-Replayed true). The same key with a different request is rejected with IDEMPOTENCY_KEY_REUSED.
Tipo
string
Longitud máx.
255Cuerpo de la petición
JSON "instance": "string", "to": "string", "type": "string", "text": "string", "reply_to": "string"
{
}
Respuestas
Replay of an earlier request with the same Idempotency-Key. Nothing new was queued.
application/json
JSON "data": { "id": "string", "instance_id": "string", "direction": "string", "from_me": true, "source": "string", "api_key_id": "string", "from_name": "string", "type": "string", "status": "string", "to": "string", "from": "string", "group_id": "string", "text": "string", "caption": "string", "media": { "mime_type": "string", "size": 0, "filename": "string", "available": true }, "location": { "latitude": 0, "longitude": 0, "name": "string", "address": "string", "url": "string", "live": true }, "contacts": [ ], "poll": { "question": "string", "multiple": true, "options": [ { "name": "string", "votes": 0 } ], "voters": 0, "votes": [ { "from": "string", "from_me": true, "options": [ "string" ], "voted_at": "string" } ], "votes_available": true }, "reply_to": "string", "forwarded": true, "reactions": [ { "emoji": "string", "from": "string", "from_me": true, "reacted_at": "string" } ], "error": { "code": "string", "message": "string" }, "created_at": "string", "queued_at": "string", "sent_at": "string", "delivered_at": "string", "read_at": "string", "failed_at": "string", "received_at": "string", "edited_at": "string", "deleted_at": "string" }
{
}
POST
/messages
Ejemplos
Bring the last 30 days of a chat from the phone
POST
/messages/history
Asks the linked phone for the messages of one chat (a direct chat by phone, or a group) older than the oldest message ZAPPIO has of it, back to 30 days ago. It is asynchronous and best effort. The phone answers in pages and ZAPPIO keeps asking until the 30 days are covered; within a minute the messages are in GET /messages with their real time, and they never trigger webhooks or count as usage. A phone linked to ZAPPIO by QR already brings its last 30 days automatically. Use this for numbers linked before, or when a chat needs to go further back. The instance must be connected; one request per chat per minute.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Cuerpo de la petición
application/json
JSON "instance": "string", "phone": "string", "group": "string"
{
}
Respuestas
Nothing was asked; reason says why (NO_MESSAGES = the chat has no message to start from, WINDOW_REACHED = it already goes back 30 days).
application/json
JSON "data": { "requested": true, "reason": "string" }
{
}
POST
/messages/history
Ejemplos
Get a message
GET
/messages/{message}
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Respuestas
The message.
application/json
JSON "data": { "id": "string", "instance_id": "string", "direction": "string", "from_me": true, "source": "string", "api_key_id": "string", "from_name": "string", "type": "string", "status": "string", "to": "string", "from": "string", "group_id": "string", "text": "string", "caption": "string", "media": { "mime_type": "string", "size": 0, "filename": "string", "available": true }, "location": { "latitude": 0, "longitude": 0, "name": "string", "address": "string", "url": "string", "live": true }, "contacts": [ ], "poll": { "question": "string", "multiple": true, "options": [ { "name": "string", "votes": 0 } ], "voters": 0, "votes": [ { "from": "string", "from_me": true, "options": [ "string" ], "voted_at": "string" } ], "votes_available": true }, "reply_to": "string", "forwarded": true, "reactions": [ { "emoji": "string", "from": "string", "from_me": true, "reacted_at": "string" } ], "error": { "code": "string", "message": "string" }, "created_at": "string", "queued_at": "string", "sent_at": "string", "delivered_at": "string", "read_at": "string", "failed_at": "string", "received_at": "string", "edited_at": "string", "deleted_at": "string" }
{
}
GET
/messages/{message}
Ejemplos
Delete a message for everyone
DELETE
/messages/{message}
Deletes one of this number's messages for everyone in the chat, as WhatsApp does, within about 2.5 days of sending it. The message keeps its content in ZAPPIO and shows deleted_at. Deleting it again changes nothing. Not billed.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Respuestas
The message, deleted for everyone.
application/json
JSON "data": { "id": "string", "instance_id": "string", "direction": "string", "from_me": true, "source": "string", "api_key_id": "string", "from_name": "string", "type": "string", "status": "string", "to": "string", "from": "string", "group_id": "string", "text": "string", "caption": "string", "media": { "mime_type": "string", "size": 0, "filename": "string", "available": true }, "location": { "latitude": 0, "longitude": 0, "name": "string", "address": "string", "url": "string", "live": true }, "contacts": [ ], "poll": { "question": "string", "multiple": true, "options": [ { "name": "string", "votes": 0 } ], "voters": 0, "votes": [ { "from": "string", "from_me": true, "options": [ "string" ], "voted_at": "string" } ], "votes_available": true }, "reply_to": "string", "forwarded": true, "reactions": [ { "emoji": "string", "from": "string", "from_me": true, "reacted_at": "string" } ], "error": { "code": "string", "message": "string" }, "created_at": "string", "queued_at": "string", "sent_at": "string", "delivered_at": "string", "read_at": "string", "failed_at": "string", "received_at": "string", "edited_at": "string", "deleted_at": "string" }
{
}
DELETE
/messages/{message}
Ejemplos
Download the media of a message
GET
/messages/{message}/media
Streams the stored file as an attachment. Only messages whose media.available is true have a file.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Respuestas
The file. Content-Type is the stored MIME type.
application/octet-stream
GET
/messages/{message}/media
Ejemplos
React to a message
POST
/messages/{message}/reaction
Reacts with one emoji to a message of the chat (sent or received), replacing this number's previous reaction to it. Not billed.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Cuerpo de la petición
application/json
JSON "emoji": "string"
{
}
Respuestas
The reaction was sent.
application/json
JSON "data": { "message_id": "string", "emoji": "string" }
{
}
POST
/messages/{message}/reaction
Ejemplos
Remove the reaction
DELETE
/messages/{message}/reaction
Removes this number's reaction to the message. Not billed.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Respuestas
The reaction was removed (emoji is null).
application/json
JSON "data": { "message_id": "string", "emoji": "string" }
{
}
DELETE
/messages/{message}/reaction
Ejemplos
Mark a message as read
POST
/messages/{message}/read
Marks a message the contact sent as read (blue ticks, if the number's privacy settings show them) and, with played, a voice note as listened. Not billed.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Cuerpo de la petición
application/json
JSON "played": true
{
}
Respuestas
Marked as read.
application/json
JSON "data": { "message_id": "string", "read": true, "played": true }
{
}
POST
/messages/{message}/read
Ejemplos
Forward a message
POST
/messages/{message}/forward
Sends a copy of a stored message (its text, or its file and caption) to another chat of the same instance, with WhatsApp's "Forwarded" mark. It is a new message - queued, billed and followed like any other (202). A file needs to be stored in ZAPPIO (media.available). Accepts an Idempotency-Key like sending.
Autorizaciones
bearerAuth
An API key created in the dashboard (Authorization: Bearer
Tipo
HTTP (bearer)
Parámetros
Header Parameters
Idempotency-Key
Same rules as for sending a message.
Tipo
string
Longitud máx.
255Cuerpo de la petición
application/json
JSON "to": "string"
{
}
Respuestas
Replay of an earlier request with the same Idempotency-Key.
application/json
JSON "data": { "id": "string", "instance_id": "string", "direction": "string", "from_me": true, "source": "string", "api_key_id": "string", "from_name": "string", "type": "string", "status": "string", "to": "string", "from": "string", "group_id": "string", "text": "string", "caption": "string", "media": { "mime_type": "string", "size": 0, "filename": "string", "available": true }, "location": { "latitude": 0, "longitude": 0, "name": "string", "address": "string", "url": "string", "live": true }, "contacts": [ ], "poll": { "question": "string", "multiple": true, "options": [ { "name": "string", "votes": 0 } ], "voters": 0, "votes": [ { "from": "string", "from_me": true, "options": [ "string" ], "voted_at": "string" } ], "votes_available": true }, "reply_to": "string", "forwarded": true, "reactions": [ { "emoji": "string", "from": "string", "from_me": true, "reacted_at": "string" } ], "error": { "code": "string", "message": "string" }, "created_at": "string", "queued_at": "string", "sent_at": "string", "delivered_at": "string", "read_at": "string", "failed_at": "string", "received_at": "string", "edited_at": "string", "deleted_at": "string" }
{
}
POST
/messages/{message}/forward