Endpoints

Referência: conversas

Números de WhatsApp, conversas e a identificação da chave.

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 conversa estão explicados em Eventos do webhook: o objeto é o mesmo.

Identificar a integração

GET /me Qualquer chave

Somente quadros permitidos; cartões privados e de canais privados são excluídos.

Exemplo de chamada

GET/mebash

curl -X GET "$NEXTCHAT_API/me" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json

{
  "board_ids": [
    "b7a43f45-ee55-48b3-b378-d4cd5a2436c5"
  ],
  "expires_at": "2027-01-20T22:26:56.333896-03:00",
  "name": "ERP da loja",
  "scopes": [
    "conversations:read",
    "conversations:write",
    "messages:read",
    "messages:send",
    "media:write",
    "contacts:read",
    "contacts:write",
    "attendances:read",
    "attendances:write",
    "team:read",
    "reports:read",
    "webhooks:manage",
    "read",
    "create",
    "update",
    "move",
    "comments:write",
    "checklist:write",
    "attachments:write",
    "attachments:delete"
  ]
}

Erros possíveis: 400, 401, 403, 404, 409, 413, 428, 429, 503. O que cada um significa e o formato: Limites e erros.

Listar números de WhatsApp

GET /channels Permissão conversations:read

Exemplo de chamada

GET/channelsbash

curl -X GET "$NEXTCHAT_API/channels" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json

[
  {
    "id": "8802af70-1081-432c-b48a-5e06df19e0e9",
    "tenant_id": "544f5085-b05f-46e1-b98f-daedf1b078dd",
    "name": "Delivery",
    "phone": "5511999990000",
    "status": "connected",
    "unread": 1,
    "avatar_url": "",
    "private": false,
    "owner_user_id": null,
    "share_kanban": false
  }
]

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

Listar conversas

GET /conversations Permissão conversations:read

Filtros (query string)

Parâmetro	Tipo	Descrição
`q`	texto	Nome, telefone ou trecho da última mensagem.
`archived`	texto	true ou false. · `true`, `false`
`unread`	texto	true = só não lidas.
`kind`	texto	direct ou group. · `direct`, `group`
`channel`	texto	UUID do número.
`assignee`	texto	none, me ou UUID.
`sector`	texto	UUID do setor.
`label`	texto	UUID da etiqueta.
`limit`	número	Itens por página.
`offset`	número	Quantos pular.

Exemplo de chamada

GET/conversationsbash

curl -X GET "$NEXTCHAT_API/conversations" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 200 · Sucesso

Resposta 200json

[
  {
    "id": "15917920-d305-4888-901a-1f4a4d713537",
    "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
    "contact_id": "d7ef5dd5-31d5-4950-b0ae-6f9ffce053b1",
    "name": "Maria Souza",
    "phone": "5511988887777",
    "lid": "",
    "last_message_preview": "a de cima",
    "last_message_at": "2026-10-22T22:26:56.286271-03:00",
    "last_message_direction": "in",
    "last_message_status": "sent",
    "last_message_id": "365800f2-86a5-43a3-b339-86b3f238b209",
    "unread_count": 2,
    "updated_at": "2026-10-22T22:26:56.28851-03:00",
    "avatar_media_id": null,
    "pinned": false,
    "muted": false,
    "archived": false,
    "label_ids": [],
    "blocked": false,
    "push_name": "Maria",
    "avatar_url": "",
    "is_group": false,
    "pinned_message": null,
    "assignee_id": null,
    "assignee_name": "",
    "sector": null,
    "sector_assigned_at": null,
    "menu": null,
    "attendance": {
      "id": "a270b2ea-057c-4186-b741-4d9e4c9059a1",
      "protocol": 1,
      "opened_by": "customer",
      "opened_at": "2026-10-22T22:26:56.252601-03:00"
    },
    "ai": null,
    "waiting_cleared_at": null
  }
]

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

Abrir conversa com um telefone ou contato

POST /conversations Permissão conversations:write

Corpo (JSON)

Campo	Tipo	Descrição
`channel_id` obrigatório	UUID	Número de WhatsApp da empresa que vai falar com o contato (GET /channels). Obrigatório.
`phone`	texto	Telefone do contato, com código do país (5511988887777). Use phone ou contact_id.
`name`	texto	Nome do contato, se ele ainda não existir.
`contact_id`	UUID	Contato já cadastrado (GET /contacts), no lugar de phone.

Exemplo de chamada

POST/conversationsbash

curl -X POST "$NEXTCHAT_API/conversations" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"8802af70-1081-432c-b48a-5e06df19e0e9","name":"João Pedro","phone":"5511977776666"}'

Resposta 201 · Criado

Resposta 201json

{
  "id": "bba3f97f-b88f-4df7-a21b-0a8156a164f6",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "contact_id": "77433951-4528-40c0-a6a0-34774cde3ec6",
  "name": "João Pedro",
  "phone": "5511977776666",
  "lid": "",
  "last_message_preview": "",
  "last_message_at": null,
  "last_message_direction": "",
  "last_message_status": "",
  "last_message_id": "",
  "unread_count": 0,
  "updated_at": "2026-10-22T22:26:56.35711-03:00",
  "avatar_media_id": null,
  "pinned": false,
  "muted": false,
  "archived": false,
  "label_ids": [],
  "blocked": false,
  "push_name": "João Pedro",
  "avatar_url": "",
  "is_group": false,
  "pinned_message": null,
  "assignee_id": null,
  "assignee_name": "",
  "sector": null,
  "sector_assigned_at": null,
  "menu": null,
  "attendance": null,
  "ai": null,
  "waiting_cleared_at": null
}

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

Detalhar conversa

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

Parâmetros do caminho

Parâmetro	Tipo	Descrição
`id` obrigatório	UUID	Identificador (UUID)

Exemplo de chamada

GET/conversations/{id}bash

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

Resposta 200 · Sucesso

Resposta 200json

{
  "id": "15917920-d305-4888-901a-1f4a4d713537",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "contact_id": "d7ef5dd5-31d5-4950-b0ae-6f9ffce053b1",
  "name": "Maria Souza",
  "phone": "5511988887777",
  "lid": "",
  "last_message_preview": "a de cima",
  "last_message_at": "2026-10-22T22:26:56.286271-03:00",
  "last_message_direction": "in",
  "last_message_status": "sent",
  "last_message_id": "365800f2-86a5-43a3-b339-86b3f238b209",
  "unread_count": 2,
  "updated_at": "2026-10-22T22:26:56.28851-03:00",
  "avatar_media_id": null,
  "pinned": false,
  "muted": false,
  "archived": false,
  "label_ids": [],
  "blocked": false,
  "push_name": "Maria",
  "avatar_url": "",
  "is_group": false,
  "pinned_message": null,
  "assignee_id": null,
  "assignee_name": "",
  "sector": null,
  "sector_assigned_at": null,
  "menu": null,
  "attendance": {
    "id": "a270b2ea-057c-4186-b741-4d9e4c9059a1",
    "protocol": 1,
    "opened_by": "customer",
    "opened_at": "2026-10-22T22:26:56.252601-03:00"
  },
  "ai": null,
  "waiting_cleared_at": null
}

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

Alterar conversa (arquivar, fixar, silenciar, nome, etiquetas)

PATCH /conversations/{id} Permissão conversations:write

Parâmetros do caminho

Parâmetro	Tipo	Descrição
`id` obrigatório	UUID	Identificador (UUID)

Corpo (JSON)

Campo	Tipo	Descrição
`archived`	sim/não	Arquiva (true) ou desarquiva (false).
`pinned`	sim/não	Fixa a conversa no topo da lista.
`muted`	sim/não	Silencia as notificações da conversa.
`name`	texto	Nome do contato mostrado na conversa (até 200 bytes).
`label_ids`	lista	Etiquetas da conversa: a lista substitui as atuais (GET /labels). · lista de UUIDs
`unread`	sim/não	true marca a conversa como não lida (volta a aparecer com o contador).
`pinned_message_id`	texto	Fixa esta mensagem no topo da conversa; "" desafixa.
`clear_waiting`	sim/não	true tira a conversa do "Esperando" até o cliente escrever de novo.
`ai`	sim/não	true marca que a IA está com a conversa; false devolve à equipe (recurso "IA" da empresa; grupos não).

Exemplo de chamada

PATCH/conversations/{id}bash

curl -X PATCH "$NEXTCHAT_API/conversations/{id}" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label_ids":["1df47ee4-7fd6-404a-b016-aec4c8d7f274"],"pinned":true}'

Resposta 200 · Sucesso

Resposta 200json

{
  "id": "15917920-d305-4888-901a-1f4a4d713537",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "contact_id": "d7ef5dd5-31d5-4950-b0ae-6f9ffce053b1",
  "name": "Maria Souza",
  "phone": "5511988887777",
  "lid": "",
  "last_message_preview": "a de cima",
  "last_message_at": "2026-10-22T22:26:56.286271-03:00",
  "last_message_direction": "in",
  "last_message_status": "sent",
  "last_message_id": "365800f2-86a5-43a3-b339-86b3f238b209",
  "unread_count": 2,
  "updated_at": "2026-10-22T22:26:56.371241-03:00",
  "avatar_media_id": null,
  "pinned": true,
  "muted": false,
  "archived": false,
  "label_ids": [
    "1df47ee4-7fd6-404a-b016-aec4c8d7f274"
  ],
  "blocked": false,
  "push_name": "Maria",
  "avatar_url": "",
  "is_group": false,
  "pinned_message": null,
  "assignee_id": null,
  "assignee_name": "",
  "sector": null,
  "sector_assigned_at": null,
  "menu": null,
  "attendance": {
    "id": "a270b2ea-057c-4186-b741-4d9e4c9059a1",
    "protocol": 1,
    "opened_by": "customer",
    "opened_at": "2026-10-22T22:26:56.252601-03:00"
  },
  "ai": null,
  "waiting_cleared_at": null
}

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

Marcar como lida

POST /conversations/{id}/read Permissão conversations:write

Parâmetros do caminho

Parâmetro	Tipo	Descrição
`id` obrigatório	UUID	Identificador (UUID)

Exemplo de chamada

POST/conversations/{id}/readbash

curl -X POST "$NEXTCHAT_API/conversations/{id}/read" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY"

Resposta 204 · Sucesso, sem corpo de resposta

Sem corpo de resposta.

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

Transferir para pessoa e/ou setor

POST /conversations/{id}/transfer Permissão conversations:write

Parâmetros do caminho

Parâmetro	Tipo	Descrição
`id` obrigatório	UUID	Identificador (UUID)

Corpo (JSON)

Campo	Tipo	Descrição
`user_id`	UUID	Pessoa que passa a ser a responsável (GET /team). Transferir para si mesmo assume a conversa.
`sector_id`	UUID	Setor de destino (GET /sectors).
`reason`	texto	Motivo, registrado no histórico da conversa.

Exemplo de chamada

POST/conversations/{id}/transferbash

curl -X POST "$NEXTCHAT_API/conversations/{id}/transfer" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Pedido grande, Ana acompanha","user_id":"c0ee6c5f-9199-4421-a6a5-290a2cfc4391"}'

Resposta 200 · Sucesso

Resposta 200json

{
  "id": "15917920-d305-4888-901a-1f4a4d713537",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "contact_id": "d7ef5dd5-31d5-4950-b0ae-6f9ffce053b1",
  "name": "Maria Souza",
  "phone": "5511988887777",
  "lid": "",
  "last_message_preview": "Segue o cardápio",
  "last_message_at": "2026-10-22T22:26:56.477244-03:00",
  "last_message_direction": "out",
  "last_message_status": "sent",
  "last_message_id": "3c83712b-16c5-4dd8-b05e-2146fbd887ec",
  "unread_count": 0,
  "updated_at": "2026-10-22T22:26:56.501103-03:00",
  "avatar_media_id": null,
  "pinned": true,
  "muted": false,
  "archived": false,
  "label_ids": [
    "1df47ee4-7fd6-404a-b016-aec4c8d7f274"
  ],
  "blocked": false,
  "push_name": "Maria",
  "avatar_url": "",
  "is_group": false,
  "pinned_message": null,
  "assignee_id": "c0ee6c5f-9199-4421-a6a5-290a2cfc4391",
  "assignee_name": "Ana Souza",
  "sector": null,
  "sector_assigned_at": null,
  "menu": null,
  "attendance": {
    "id": "a270b2ea-057c-4186-b741-4d9e4c9059a1",
    "protocol": 1,
    "opened_by": "customer",
    "opened_at": "2026-10-22T22:26:56.252601-03:00"
  },
  "ai": null,
  "waiting_cleared_at": null
}

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

Definir o setor

PUT /conversations/{id}/sector Permissão conversations:write

Parâmetros do caminho

Parâmetro	Tipo	Descrição
`id` obrigatório	UUID	Identificador (UUID)

Corpo (JSON)

Campo	Tipo	Descrição
`sector_id`	UUID	Setor da conversa (GET /sectors); null tira do setor. · aceita null
`reason`	texto	Motivo, registrado no histórico.

Exemplo de chamada

PUT/conversations/{id}/sectorbash

curl -X PUT "$NEXTCHAT_API/conversations/{id}/sector" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"Pedido","sector_id":"c3230317-bdb6-4f3b-b33d-51d4eb61e5d1"}'

Resposta 200 · Sucesso

Resposta 200json

{
  "id": "15917920-d305-4888-901a-1f4a4d713537",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "contact_id": "d7ef5dd5-31d5-4950-b0ae-6f9ffce053b1",
  "name": "Maria Souza",
  "phone": "5511988887777",
  "lid": "",
  "last_message_preview": "Segue o cardápio",
  "last_message_at": "2026-10-22T22:26:56.477244-03:00",
  "last_message_direction": "out",
  "last_message_status": "sent",
  "last_message_id": "3c83712b-16c5-4dd8-b05e-2146fbd887ec",
  "unread_count": 0,
  "updated_at": "2026-10-22T22:26:56.513696-03:00",
  "avatar_media_id": null,
  "pinned": true,
  "muted": false,
  "archived": false,
  "label_ids": [
    "1df47ee4-7fd6-404a-b016-aec4c8d7f274"
  ],
  "blocked": false,
  "push_name": "Maria",
  "avatar_url": "",
  "is_group": false,
  "pinned_message": null,
  "assignee_id": "c0ee6c5f-9199-4421-a6a5-290a2cfc4391",
  "assignee_name": "Ana Souza",
  "sector": {
    "id": "c3230317-bdb6-4f3b-b33d-51d4eb61e5d1",
    "name": "Pedidos",
    "color": "red"
  },
  "sector_assigned_at": "2026-10-22T22:26:56.513696-03:00",
  "menu": null,
  "attendance": {
    "id": "a270b2ea-057c-4186-b741-4d9e4c9059a1",
    "protocol": 1,
    "opened_by": "customer",
    "opened_at": "2026-10-22T22:26:56.252601-03:00"
  },
  "ai": null,
  "waiting_cleared_at": null
}

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