Ir al contenido

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo
HTTP (bearer)

Parámetros​

Query Parameters

instance

Only messages of this instance.

Tipo
string
Longitud máx.
40
direction
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.
120
limit

Page size (default 25).

Tipo
integer
Mínimo
1
Máximo
100
cursor

Opaque cursor from a previous page (meta.next_cursor).

Tipo
string
Longitud máx.
512
phone

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.
32
group

Only the messages of this group (grp_…). Not with phone.

Tipo
string
Longitud máx.
40
since

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.
40
until

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.
40

Respuestas​

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"
  
}
}

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

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.
255

Cuerpo 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"
  
}
}

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

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"
  
}
}

Ejemplos​


Get a message​

GET
/messages/{message}

Autorizaciones​

bearerAuth

An API key created in the dashboard (Authorization: Bearer ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

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"
  
}
}

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

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"
  
}
}

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo
HTTP (bearer)

Respuestas​

The file. Content-Type is the stored MIME type.

application/octet-stream

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

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"
  
}
}

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo
HTTP (bearer)

Respuestas​

The reaction was removed (emoji is null).

application/json
JSON
{
  
"data": {
  
  
"message_id": "string",
  
  
"emoji": "string"
  
}
}

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

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
  
}
}

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 ). The scopes listed on each operation must be granted to the key: instances:read, instances:write, messages:read, messages:send, webhooks:read, webhooks:write.

Tipo
HTTP (bearer)

Parámetros​

Header Parameters

Idempotency-Key

Same rules as for sending a message.

Tipo
string
Longitud máx.
255

Cuerpo 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"
  
}
}

Ejemplos​