Abrir NextChat
Endpoints

Referência: mensagens e arquivos

Ler e enviar mensagens, enviar arquivos e pedir o link de um arquivo.

Nesta página

Todos os exemplos de resposta foram gerados chamando a API de verdade. Os caminhos são relativos à base URL e toda chamada leva Authorization: Bearer nck_….

Base URLhttps://app.nextchat.nextsistem.dev.br/api/integrations/v1

Os campos da mensagem e do arquivo estão explicados em Eventos do webhook: o objeto é o mesmo. Para enviar um arquivo: primeiro POST /media, depois POST /conversations/{id}/messages com o media_id.

Ler mensagens

GET /conversations/{id}/messages Permissão messages:read

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Filtros (query string)

ParâmetroTipoDescrição
limitnúmeroItens (1 a 100).
beforetextoCursor para mensagens mais antigas.
aftertextoCursor para mensagens mais novas.

Exemplo de chamada

GET/conversations/{id}/messagesbash
curl -X GET "$NEXTCHAT_API/conversations/{id}/messages" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
{
  "items": [
    {
      "id": "365800f2-86a5-43a3-b339-86b3f238b209",
      "conversation_id": "15917920-d305-4888-901a-1f4a4d713537",
      "external_id": "3EB0D5F1A9C27E4B80",
      "client_id": null,
      "direction": "in",
      "sender_user_id": null,
      "sender_name": null,
      "origin": "phone",
      "type": "image",
      "body": "a de cima",
      "reply_to_external_id": "",
      "status": "sent",
      "error": null,
      "sent_at": "2026-10-22T22:26:56.286271-03:00",
      "created_at": "2026-10-22T22:26:56.28851-03:00",
      "media_id": "3d881d3d-2012-442e-a736-e4c707d975e6",
      "media": {
        "id": "3d881d3d-2012-442e-a736-e4c707d975e6",
        "kind": "image",
        "mime_type": "image/jpeg",
        "file_name": "foto.jpg",
        "size_bytes": 597,
        "duration_ms": 0,
        "voice": false,
        "gif": false,
        "url": "https://arquivos.exemplo/544f5085-b05f-46e1-b98f-daedf1b078dd/3d881d3d-2012-442e-a736-e4c707d975e6?X-Amz-Signature=…"
      },
      "media_error": null,
      "edited_at": null,
      "reactions": [],
      "group_sender": null,
      "starred": false,
      "forwarded": false,
      "hidden": false,
      "owner_at_send": null,
      "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9"
    },
    {
      "id": "75fe627c-54c6-4377-b27b-5a7a1ae8d7d2",
      "conversation_id": "15917920-d305-4888-901a-1f4a4d713537",
      "external_id": "3EB0C431D5A2F8B6E1",
      "client_id": null,
      "direction": "in",
      "sender_user_id": null,
      "sender_name": null,
      "origin": "phone",
      "type": "text",
      "body": "Quero 2 pizzas grandes",
      "reply_to_external_id": "",
      "status": "sent",
      "error": null,
      "sent_at": "2026-10-22T22:26:56.224199-03:00",
      "created_at": "2026-10-22T22:26:56.233024-03:00",
      "media_id": null,
      "media": null,
      "media_error": null,
      "edited_at": null,
      "reactions": [],
      "group_sender": null,
      "starred": false,
      "forwarded": false,
      "hidden": false,
      "owner_at_send": null,
      "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9"
    }
  ],
  "next_cursor": ""
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Enviar mensagem (idempotente por client_id)

POST /conversations/{id}/messages Permissão messages:send

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Corpo (JSON)

CampoTipoDescrição
client_id obrigatórioUUIDUUID escolhido por você; repetir não reenvia.
texttextoTexto da mensagem, ou a legenda do arquivo.
media_idUUIDArquivo enviado antes com POST /media.
reply_to_external_idtextoexternal_id da mensagem que esta responde (aparece como resposta no WhatsApp).

Exemplo de chamada

Texto · POST /conversations/{id}/messagesbash
curl -X POST "$NEXTCHAT_API/conversations/{id}/messages" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"776b1982-a105-459e-9f35-6564d6394cdd","text":"Anotado! Já já sai."}'
Com arquivo · POST /conversations/{id}/messagesbash
curl -X POST "$NEXTCHAT_API/conversations/{id}/messages" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"client_id":"e426e2c4-9c13-4ba6-b0d1-289042ec300e","media_id":"cf870fe4-7fa4-4560-9f71-5718dd051d88","text":"Segue o cardápio"}'

Resposta 201 · Criado

Resposta · Textojson
{
  "id": "cd5c2bdf-e565-456e-bda8-93a1e7526d75",
  "conversation_id": "15917920-d305-4888-901a-1f4a4d713537",
  "external_id": "776B1982A105459E9F356564D6394CDD",
  "client_id": "776b1982-a105-459e-9f35-6564d6394cdd",
  "direction": "out",
  "sender_user_id": "5c82d935-9e12-41d5-b3ff-5ea839823470",
  "sender_name": "Amanda Costa",
  "origin": "app",
  "type": "text",
  "body": "Anotado! Já já sai.",
  "reply_to_external_id": "",
  "status": "sent",
  "error": null,
  "sent_at": "2026-10-22T22:26:56.454512-03:00",
  "created_at": "2026-10-22T22:26:56.396776-03:00",
  "media_id": null,
  "media": null,
  "media_error": null,
  "edited_at": null,
  "reactions": [],
  "group_sender": null,
  "starred": false,
  "forwarded": false,
  "hidden": false,
  "owner_at_send": null,
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9"
}
Resposta · Com arquivojson
{
  "id": "3c83712b-16c5-4dd8-b05e-2146fbd887ec",
  "conversation_id": "15917920-d305-4888-901a-1f4a4d713537",
  "external_id": "E426E2C49C134BA6B0D1289042EC300E",
  "client_id": "e426e2c4-9c13-4ba6-b0d1-289042ec300e",
  "direction": "out",
  "sender_user_id": "5c82d935-9e12-41d5-b3ff-5ea839823470",
  "sender_name": "Amanda Costa",
  "origin": "app",
  "type": "document",
  "body": "Segue o cardápio",
  "reply_to_external_id": "",
  "status": "sent",
  "error": null,
  "sent_at": "2026-10-22T22:26:56.480816-03:00",
  "created_at": "2026-10-22T22:26:56.477677-03:00",
  "media_id": "cf870fe4-7fa4-4560-9f71-5718dd051d88",
  "media": {
    "id": "cf870fe4-7fa4-4560-9f71-5718dd051d88",
    "kind": "document",
    "mime_type": "application/pdf",
    "file_name": "cardapio.pdf",
    "size_bytes": 20,
    "duration_ms": 0,
    "voice": false,
    "gif": false,
    "url": "https://arquivos.exemplo/544f5085-b05f-46e1-b98f-daedf1b078dd/cf870fe4-7fa4-4560-9f71-5718dd051d88?X-Amz-Signature=…"
  },
  "media_error": null,
  "edited_at": null,
  "reactions": [],
  "group_sender": null,
  "starred": false,
  "forwarded": false,
  "hidden": false,
  "owner_at_send": null,
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9"
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Uma mensagem

GET /messages/{id} Permissão messages:read

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Exemplo de chamada

GET/messages/{id}bash
curl -X GET "$NEXTCHAT_API/messages/{id}" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
{
  "id": "cd5c2bdf-e565-456e-bda8-93a1e7526d75",
  "conversation_id": "15917920-d305-4888-901a-1f4a4d713537",
  "external_id": "776B1982A105459E9F356564D6394CDD",
  "client_id": "776b1982-a105-459e-9f35-6564d6394cdd",
  "direction": "out",
  "sender_user_id": "5c82d935-9e12-41d5-b3ff-5ea839823470",
  "sender_name": "Amanda Costa",
  "origin": "app",
  "type": "text",
  "body": "Anotado! Já já sai.",
  "reply_to_external_id": "",
  "status": "sent",
  "error": null,
  "sent_at": "2026-10-22T22:26:56.454512-03:00",
  "created_at": "2026-10-22T22:26:56.396776-03:00",
  "media_id": null,
  "media": null,
  "media_error": null,
  "edited_at": null,
  "reactions": [],
  "group_sender": null,
  "starred": false,
  "forwarded": false,
  "hidden": false,
  "owner_at_send": null,
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9"
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

Enviar arquivo (multipart/form-data, campo file)

POST /media Permissão media:write

Corpo (multipart/form-data)

Envie o arquivo no campo file.

Exemplo de chamada

POST/mediabash
curl -X POST "$NEXTCHAT_API/media" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -F "[email protected]"

Resposta 201 · Criado

Resposta 201json
{
  "id": "cf870fe4-7fa4-4560-9f71-5718dd051d88",
  "kind": "document",
  "mime_type": "application/pdf",
  "file_name": "cardapio.pdf",
  "size_bytes": 20,
  "duration_ms": 0,
  "voice": false,
  "gif": false
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

GET /media/{id}/url Permissão messages:read

Parâmetros do caminho

ParâmetroTipoDescrição
id obrigatórioUUIDIdentificador (UUID)

Exemplo de chamada

GET/media/{id}/urlbash
curl -X GET "$NEXTCHAT_API/media/{id}/url" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json
{
  "expires_in": 300,
  "url": "https://arquivos.exemplo/544f5085-b05f-46e1-b98f-daedf1b078dd/cf870fe4-7fa4-4560-9f71-5718dd051d88?X-Amz-Signature=…"
}

Erros possíveis: 401, 403, 429. O que cada um significa e o formato: Limites e erros.

↑ ↓ navegar↵ abrirEsc fechar