Chats

Conversas: listar, ler o histórico, editar e apagar mensagens, marcar como lidas.

Basehttps://app.onzap.io/v1/instances/{instanceId}AuthX-Instance-Token: SEU_TOKEN

Listar chats

GET/v1/instances/{instanceId}/chats

API OnZap

Parâmetros de query

sortBystringopcional

Sort by field

sortOrderstringopcional

Sort order - descending (Z => A, New first) or ascending (A => Z, Old first)

mergebooleanopcional

Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact

limitnumberopcional

offsetnumberopcional

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Sucesso

Visão geral dos chats

GET/v1/instances/{instanceId}/chats/overview

API OnZap

Parâmetros de query

mergebooleanopcional

Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact

limitnumberopcional

offsetnumberopcional

idsarray de stringopcional

Filter by chat ids

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/overview" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

[
  {
    "_chat": {},
    "id": "5511999999999@c.us",
    "lastMessage": {},
    "name": "Maria Silva",
    "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…"
  }
]

Visão geral dos chats (POST)

POST/v1/instances/{instanceId}/chats/overview

API OnZap

Corpo (JSON)

paginationobjectobrigatório

pagination.limitnumberopcional

pagination.mergebooleanopcional

Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact

pagination.offsetnumberopcional

filterobjectopcional

filter.idsarray de stringopcional

Filter by chat ids

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/overview" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pagination": {}
  }'

Resposta

[
  {
    "_chat": {},
    "id": "5511999999999@c.us",
    "lastMessage": {},
    "name": "Maria Silva",
    "picture": "https://app.onzap.io/v1/avatars/i01jabcdefghjkmnpqrstvwxyz/5511999999999@c.us?exp=1767229200&sig=…"
  }
]

Foto do chat

GET/v1/instances/{instanceId}/chats/{chatId}/picture

API OnZap

Parâmetros do caminho

chatIdstringobrigatório

Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid).

Parâmetros de query

refreshbooleanopcional

Refresh the picture from the server (24h cache by default). Do not refresh if not needed, you can get rate limit error

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/picture" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

{
  "url": "https://exemplo.com.br/arquivos/pedido.jpg"
}

Mensagens do chat

GET/v1/instances/{instanceId}/chats/{chatId}/messages

API OnZap

Histórico da conversa, das mais novas para as mais antigas. Com downloadMedia=true, as mídias vêm com link assinado.

Parâmetros do caminho

chatIdstringobrigatório

Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid).

Parâmetros de query

sortBystringopcional

Sort by field

sortOrderstringopcional

Sort order - descending (Z => A, New first) or ascending (A => Z, Old first)

downloadMediabooleanopcional

Download media for messages

mergebooleanopcional

Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact

limitnumberobrigatório

offsetnumberopcional

filter.timestamp.ltenumberopcional

Filter messages before this timestamp (inclusive)

filter.timestamp.gtenumberopcional

Filter messages after this timestamp (inclusive)

filter.fromMebooleanopcional

From me filter (by default shows all messages)

filter.ackstringopcional

Filter messages by acknowledgment status

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages?limit=VALOR" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

[
  {
    "_data": {},
    "ack": -1,
    "ackName": "READ",
    "author": "5521988887777@c.us",
    "body": "Olá! Seu pedido foi confirmado.",
    "from": "5511999999999@c.us",
    "fromMe": false,
    "hasMedia": false,
    "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
    "location": {
      "address": "Av. Paulista, 1000 - São Paulo, SP",
      "description": "Atendimento de segunda a sexta, das 9h às 18h.",
      "latitude": "-23.5613",
      "live": false,
      "longitude": "-46.6565",
      "name": "Loja Centro",
      "thumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD…",
      "url": "https://exemplo.com.br/arquivos/pedido.jpg"
    },
    "media": {
      "error": {},
      "filename": "example.pdf",
      "mimetype": "audio/jpeg",
      "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
    },
    "mediaUrl": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…",
    "participant": "5521988887777@c.us",
    "replyTo": {
      "_data": {},
      "body": "Hello!",
      "hasMedia": false,
      "id": "AAAAAAAAAAAAAAAAAAAA",
      "media": {
        "error": {},
        "filename": "example.pdf",
        "mimetype": "audio/jpeg",
        "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
      },
      "participant": "5511999999999@c.us"
    },
    "source": "api",
    "timestamp": 1666943582,
    "to": "5511999999999@c.us",
    "vCards": [
      "texto"
    ]
  }
]

Ler mensagens não lidas do chat

POST/v1/instances/{instanceId}/chats/{chatId}/messages/read

API OnZap

Parâmetros do caminho

chatIdstringobrigatório

Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid).

Parâmetros de query

messagesnumberopcional

How much messages to read (latest first)

daysnumberopcional

How much days to read (latest first)

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/read" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

{
  "ids": [
    "texto"
  ]
}

Mensagem por ID

GET/v1/instances/{instanceId}/chats/{chatId}/messages/{messageId}

API OnZap

Parâmetros do caminho

chatIdstringobrigatório

Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid).

messageIdstringobrigatório

Parâmetros de query

downloadMediabooleanopcional

Download media for messages

mergebooleanopcional

Merge LID (@lid) and phone-number (@c.us) chats referencing the same contact

Requisição

curl "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/false_5511999999999@c.us_3EB0C0A1B2C3D4E5F6" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

{
  "_data": {},
  "ack": -1,
  "ackName": "READ",
  "author": "5521988887777@c.us",
  "body": "Olá! Seu pedido foi confirmado.",
  "from": "5511999999999@c.us",
  "fromMe": false,
  "hasMedia": false,
  "id": "false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA",
  "location": {
    "address": "Av. Paulista, 1000 - São Paulo, SP",
    "description": "Atendimento de segunda a sexta, das 9h às 18h.",
    "latitude": "-23.5613",
    "live": false,
    "longitude": "-46.6565",
    "name": "Loja Centro",
    "thumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD…",
    "url": "https://exemplo.com.br/arquivos/pedido.jpg"
  },
  "media": {
    "error": {},
    "filename": "example.pdf",
    "mimetype": "audio/jpeg",
    "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
  },
  "mediaUrl": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…",
  "participant": "5521988887777@c.us",
  "replyTo": {
    "_data": {},
    "body": "Hello!",
    "hasMedia": false,
    "id": "AAAAAAAAAAAAAAAAAAAA",
    "media": {
      "error": {},
      "filename": "example.pdf",
      "mimetype": "audio/jpeg",
      "url": "https://app.onzap.io/v1/files/i01jabcdefghjkmnpqrstvwxyz/false_5511999999999@c.us_AAAAAAAAAAAAAAAAAAAA.oga?exp=1767229200&sig=…"
    },
    "participant": "5511999999999@c.us"
  },
  "source": "api",
  "timestamp": 1666943582,
  "to": "5511999999999@c.us",
  "vCards": [
    "texto"
  ]
}

Apagar mensagem

DELETE/v1/instances/{instanceId}/chats/{chatId}/messages/{messageId}

API OnZap

Parâmetros do caminho

chatIdstringobrigatório

Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid).

messageIdstringobrigatório

Message ID in format {fromMe}{chat}{message_id}[_{participant}]

Requisição

curl -X DELETE "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/true_123456789@c.us_BAE6A33293978B16" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

Sucesso

Editar mensagem

PUT/v1/instances/{instanceId}/chats/{chatId}/messages/{messageId}

API OnZap

Parâmetros do caminho

chatIdstringobrigatório

Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid).

messageIdstringobrigatório

Message ID in format {fromMe}{chat}{message_id}[_{participant}]

Corpo (JSON)

textstringobrigatório

linkPreviewbooleanopcional

linkPreviewHighQualitybooleanopcional

mentionsarray de stringopcional

Chat IDs to mention in the message. Use ["all"] to mention all participants in a group.

Requisição

curl -X PUT "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/messages/true_123456789@c.us_BAE6A33293978B16" \
  -H "X-Instance-Token: $ONZAP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, world!"
  }'

Resposta

Sucesso

Marcar chat como não lido

POST/v1/instances/{instanceId}/chats/{chatId}/unread

API OnZap

Parâmetros do caminho

chatIdstringobrigatório

Conversa: número com DDI e DDD (5511999999999) ou JID (…@c.us, …@g.us, …@lid).

Requisição

curl -X POST "https://app.onzap.io/v1/instances/SUA_INSTANCIA/chats/5511999999999/unread" \
  -H "X-Instance-Token: $ONZAP_TOKEN"

Resposta

{}