Response Format

SuccessCopy Anchor Link

A successful response wraps the result in data. It is an object or an array, depending on the route.

{
  "data": {
    "message_id": "true_5581999999999@c.us_3EB0C767D26A1D5E",
    "chat_id": "5581999999999@c.us"
  }
}

Most routes answer 200. Creating a label or a group answers 201.

Lists and paginationCopy Anchor Link

The list routes take limit and offset and return a plain array in data, with no total count.

For the next page, advance offset by limit. Stop when a page comes back empty. Messages also accept before and after (Unix seconds, exclusive) to filter by time.

Data passed through from WhatsAppCopy Anchor Link

Some group routes (GET /groups, POST /groups, GET /groups/{gid}, GET /groups/{gid}/participants, and adding or removing participants) return the data as WhatsApp gives it, unchanged. Its fields may vary: read only what you need and don't fail on fields you don't know.

ErrorsCopy Anchor Link

Every error has the same shape:

{
  "error": {
    "codigo": "numero_sem_whatsapp",
    "mensagem": "Este numero nao tem conta no WhatsApp. Nada foi enviado."
  }
}

Common error codesCopy Anchor Link

Route-specific codes, such as formato_de_voz_invalido, lista_so_individual or etiquetas_indisponiveis, are explained in the guides and listed per route in the API Reference tab.

Response headersCopy Anchor Link

IdempotencyCopy Anchor Link

Every route that changes something (POST, PUT, PATCH and DELETE) accepts the optional Idempotency-Key header. Repeating the same value, with the same API key, within 24 hours returns the first response with idempotent-replayed: true, without sending again.

• Use one value per message: a UUID, your order id or the id of the workflow run.
• Same value, different request (other body or other route): 422 idempotency_key_reutilizada.
• First request still running: 409 requisicao_em_andamento. Wait for it.
• Error where nothing went out (validation, 402, 409, 422...): the value is released, so you can fix the request and retry with the same value.
• resultado_incerto: the value stays taken, and a retry returns the same error instead of risking a duplicate message.