Endpoints

Referência: contatos

Contatos e etiquetas.

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

Listar contatos

GET /contacts Permissão contacts:read

Filtros (query string)

Parâmetro	Tipo	Descrição
`q`	texto	Nome ou telefone.
`label`	texto	UUID da etiqueta.
`channel`	texto	UUID do número.
`limit`	número	Itens.
`offset`	número	Quantos pular.

Exemplo de chamada

GET/contactsbash

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

Resposta 200 · Sucesso

Resposta 200json

{
  "items": [
    {
      "id": "77433951-4528-40c0-a6a0-34774cde3ec6",
      "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
      "name": "João Pedro",
      "push_name": "João Pedro",
      "phonebook_name": "",
      "phone": "5511977776666",
      "lid": "",
      "company": "",
      "city": "",
      "customer_since": null,
      "label_ids": [],
      "blocked": false,
      "avatar_media_id": null,
      "avatar_url": "",
      "conversation_id": "bba3f97f-b88f-4df7-a21b-0a8156a164f6",
      "last_conversation_at": null,
      "created_at": "2026-10-22T22:26:56.356364-03:00"
    },
    {
      "id": "d7ef5dd5-31d5-4950-b0ae-6f9ffce053b1",
      "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
      "name": "Maria Souza",
      "push_name": "Maria",
      "phonebook_name": "",
      "phone": "5511988887777",
      "lid": "",
      "company": "",
      "city": "",
      "customer_since": null,
      "label_ids": [
        "1df47ee4-7fd6-404a-b016-aec4c8d7f274"
      ],
      "blocked": false,
      "avatar_media_id": null,
      "avatar_url": "",
      "conversation_id": "15917920-d305-4888-901a-1f4a4d713537",
      "last_conversation_at": "2026-10-22T22:26:56.477244-03:00",
      "created_at": "2026-10-22T22:26:56.225071-03:00"
    }
  ],
  "total": 2
}

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

Criar contato

POST /contacts Permissão contacts:write

Corpo (JSON)

Campo	Tipo	Descrição
`name` obrigatório	texto	Nome do contato.
`phone` obrigatório	texto	Telefone com código do país (5511966665555).
`company`	texto	Empresa do contato.
`city`	texto	Cidade.
`channel_id`	UUID	Número de WhatsApp de referência do contato (opcional).

Exemplo de chamada

POST/contactsbash

curl -X POST "$NEXTCHAT_API/contacts" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"Campinas","company":"Lima Contabilidade","name":"Carlos Lima","phone":"5511966665555"}'

Resposta 201 · Criado

Resposta 201json

{
  "id": "622ca53d-4044-436f-9b2f-bf76c0456a57",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "name": "Carlos Lima",
  "push_name": "",
  "phonebook_name": "",
  "phone": "5511966665555",
  "lid": "",
  "company": "Lima Contabilidade",
  "city": "Campinas",
  "customer_since": null,
  "label_ids": [],
  "blocked": false,
  "avatar_media_id": null,
  "avatar_url": "",
  "conversation_id": null,
  "last_conversation_at": null,
  "created_at": "2026-10-22T22:26:56.486032-03:00"
}

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

Detalhar contato

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

Parâmetros do caminho

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

Exemplo de chamada

GET/contacts/{id}bash

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

Resposta 200 · Sucesso

Resposta 200json

{
  "id": "622ca53d-4044-436f-9b2f-bf76c0456a57",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "name": "Carlos Lima",
  "push_name": "",
  "phonebook_name": "",
  "phone": "5511966665555",
  "lid": "",
  "company": "Lima Contabilidade",
  "city": "Campinas",
  "customer_since": null,
  "label_ids": [],
  "blocked": false,
  "avatar_media_id": null,
  "avatar_url": "",
  "conversation_id": null,
  "last_conversation_at": null,
  "created_at": "2026-10-22T22:26:56.486032-03:00"
}

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

Editar contato

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

Parâmetros do caminho

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

Corpo (JSON)

Campo	Tipo	Descrição
`name`	texto	Nome salvo pela equipe.
`company`	texto	Empresa.
`city`	texto	Cidade.
`label_ids`	lista	Etiquetas do contato: a lista substitui as atuais. · lista de UUIDs
`blocked`	sim/não	Bloqueia (true) ou desbloqueia o contato.

Exemplo de chamada

PATCH/contacts/{id}bash

curl -X PATCH "$NEXTCHAT_API/contacts/{id}" \
  -H "Authorization: Bearer $NEXTCHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city":"São Paulo","label_ids":["1df47ee4-7fd6-404a-b016-aec4c8d7f274"]}'

Resposta 200 · Sucesso

Resposta 200json

{
  "id": "622ca53d-4044-436f-9b2f-bf76c0456a57",
  "channel_id": "8802af70-1081-432c-b48a-5e06df19e0e9",
  "name": "Carlos Lima",
  "push_name": "",
  "phonebook_name": "",
  "phone": "5511966665555",
  "lid": "",
  "company": "Lima Contabilidade",
  "city": "São Paulo",
  "customer_since": null,
  "label_ids": [
    "1df47ee4-7fd6-404a-b016-aec4c8d7f274"
  ],
  "blocked": false,
  "avatar_media_id": null,
  "avatar_url": "",
  "conversation_id": null,
  "last_conversation_at": null,
  "created_at": "2026-10-22T22:26:56.486032-03:00"
}

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

Listar etiquetas

GET /labels Permissão contacts:read

Exemplo de chamada

GET/labelsbash

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

Resposta 200 · Sucesso

Resposta 200json

[
  {
    "id": "1df47ee4-7fd6-404a-b016-aec4c8d7f274",
    "name": "Cliente VIP",
    "color": "#fde68a",
    "text_color": "#3F3F46",
    "contact_count": 2,
    "personal": false
  }
]

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