Conversas

Gerencie conversas com clientes nos canais de atendimento habilitados. Uma conversa representa uma thread de mensagens entre um contato e sua equipe.

Base URL e escopo de conta

Todos os endpoints usam o prefixo /api/v1/accounts/{account_id}. O conversation_id na URL é o display_id — um número sequencial por conta, não um identificador global. Toda operação é resolvida estritamente dentro da conta autenticada pelo token; não é possível acessar conversas de outra conta.

GET/api/v1/accounts/{account_id}/conversations

Retorna uma lista paginada de conversas com filtros opcionais.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`assignee_type`(query)	`string`	Nao	Filtrar por tipo de atribuição: me, unassigned, all, assigned
`status`(query)	`string`	Nao	Filtrar por status: open, resolved, pending, snoozed, all
`q`(query)	`string`	Nao	Buscar por texto nas mensagens
`inbox_id`(query)	`integer`	Nao	Filtrar por inbox
`team_id`(query)	`integer`	Nao	Filtrar por equipe
`labels`(query)	`array`	Nao	Filtrar por etiquetas
`page`(query)	`integer`	Nao	Número da página para paginação

curl -s "https://chat.seudominio.com/api/v1/accounts/1/conversations?status=open&page=1" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Lista de conversas com metadados

json

{
  "data": {
    "meta": {
      "mine_count": 5,
      "unassigned_count": 12,
      "all_count": 42
    },
    "payload": [
      {
        "id": 123,
        "inbox_id": 1,
        "status": "open",
        "messages": [...],
        "contact": { "id": 456, "name": "Joao Silva" },
        "assignee": { "id": 1, "name": "Agente 1" }
      }
    ]
  }
}

POST/api/v1/accounts/{account_id}/conversations

Cria uma nova conversa com um contato em um inbox específico.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta

Body

Nome	Tipo	Obrigatorio	Descricao
`inbox_id`	`integer`	Sim	ID do inbox onde criar a conversa
`contact_id`	`integer`	Nao	ID do contato. Informe contact_id OU source_id (um dos dois é necessário).
`source_id`	`string`	Nao	ID da origem do contato (contact source). Alternativa a contact_id.
`status`	`string`	Nao	Status inicial: open, pending
`assignee_id`	`integer`	Nao	ID do agente responsável
`team_id`	`integer`	Nao	ID da equipe responsável
`message`	`object`	Nao	Mensagem inicial: { content, content_type }

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "contact_source_id",
    "inbox_id": 1,
    "message": {
      "content": "Ola, como posso ajudar?"
    }
  }'

200Conversa criada (o contato vem em meta.sender; created_at é um inteiro epoch)

json

{
  "id": 124,
  "account_id": 1,
  "inbox_id": 1,
  "status": "open",
  "priority": null,
  "uuid": "…",
  "labels": [],
  "additional_attributes": {},
  "messages": [],
  "meta": {
    "sender": { "id": 456, "name": "Joao Silva" },
    "assignee": null,
    "team": null
  },
  "created_at": 1771151400
}

GET/api/v1/accounts/{account_id}/conversations/{conversation_id}

Retorna os detalhes completos de uma conversa específica.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`conversation_id`(path)	`integer`	Sim	ID numérico da conversa

bash

curl -s "https://chat.seudominio.com/api/v1/accounts/1/conversations/123" \
  -H "api_access_token: YOUR_TOKEN" | jq .

200Detalhes da conversa (contact/assignee/team vivem em meta; created_at é inteiro epoch)

json

{
  "id": 123,
  "inbox_id": 1,
  "status": "open",
  "priority": "medium",
  "labels": ["vip", "urgente"],
  "additional_attributes": {},
  "meta": {
    "sender": { "id": 456, "name": "Joao Silva" },
    "assignee": { "id": 1, "name": "Agente 1" },
    "team": { "id": 2, "name": "Suporte" }
  },
  "created_at": 1771151400
}

PATCH/api/v1/accounts/{account_id}/conversations/{conversation_id}

Atualiza a prioridade de uma conversa. Para status, atribuição e equipe, use os endpoints dedicados (toggle_status, toggle_priority, assignments).

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`account_id`(path)	`integer`	Sim	ID numérico da conta
`conversation_id`(path)	`integer`	Sim	display_id numérico da conversa

Body

Nome	Tipo	Obrigatorio	Descricao
`priority`	`string`	Nao	Prioridade: none, low, medium, high, urgent

Apenas priority é aceito neste endpoint

O endpoint PATCH de conversa permite somente o campo priority. Use POST .../toggle_status para alterar status e POST .../assignments para atribuir agente ou equipe.

bash

curl -X PATCH "https://chat.seudominio.com/api/v1/accounts/1/conversations/123" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "high" }'

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_status

Alterna o status da conversa (abrir/resolver/pendente).

Body

Nome	Tipo	Obrigatorio	Descricao
`status`	`string`	Sim	Novo status: open, resolved, pending, snoozed

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/toggle_status" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "status": "resolved" }'

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/toggle_priority

Define a prioridade da conversa.

Body

Nome	Tipo	Obrigatorio	Descricao
`priority`	`string`	Sim	Prioridade: none, low, medium, high, urgent

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/toggle_priority" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "priority": "urgent" }'

POST/api/v1/accounts/{account_id}/conversations/filter

Filtra conversas usando critérios avançados com operadores lógicos.

Body

Nome	Tipo	Obrigatorio	Descricao
`payload`	`array`	Sim	Array de filtros com attribute_key, filter_operator, values e query_operator

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/filter" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": [
      {
        "attribute_key": "status",
        "filter_operator": "equal_to",
        "values": ["open"],
        "query_operator": "AND"
      },
      {
        "attribute_key": "assignee_id",
        "filter_operator": "equal_to",
        "values": [1]
      }
    ]
  }'

Filtrando por data

Os atributos created_at e last_activity_at aceitam os operadores equal_to, not_equal_to, is_greater_than, is_less_than e days_before. Use equal_topara isolar um dia específico — a comparação é feita por data, então a hora da conversa não importa.

O valor deve estar no formato ISO-8601 AAAA-MM-DD. Qualquer outro formato é recusado com 422. Para days_before, o valor é o número de dias, não uma data.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/filter" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": [
      {
        "attribute_key": "created_at",
        "filter_operator": "equal_to",
        "values": ["2026-08-13"]
      }
    ]
  }'

GET/api/v1/accounts/{account_id}/conversations/meta

Retorna contadores de conversas agrupados por status e atribuição.

Parâmetros

Nome	Tipo	Obrigatorio	Descricao
`status`(query)	`string`	Nao	Filtrar por status
`q`(query)	`string`	Nao	Buscar por texto
`inbox_id`(query)	`integer`	Nao	Filtrar por inbox
`team_id`(query)	`integer`	Nao	Filtrar por equipe
`labels`(query)	`array`	Nao	Filtrar por etiquetas

200Contadores de conversas

json

{
  "meta": {
    "mine_count": 5,
    "unassigned_count": 12,
    "assigned_count": 8,
    "all_count": 25
  }
}

Etiquetas da Conversa

GET/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels

Lista as etiquetas associadas a uma conversa.

200Lista de etiquetas

json

{ "payload": ["vip", "urgente", "suporte-tecnico"] }

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/labels

Define as etiquetas de uma conversa (substitui todas as existentes).

Body

Nome	Tipo	Obrigatorio	Descricao
`labels`	`array`	Sim	Array de strings com as etiquetas

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/labels" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "labels": ["vip", "alta-prioridade"] }'

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/assignments

Atribui um agente a uma conversa.

Body

Nome	Tipo	Obrigatorio	Descricao
`assignee_id`	`integer`	Nao	ID do agente (0 para remover atribuição). Atribui agente quando presente.
`assignee_type`	`string`	Nao	Use "AgentBot" para atribuir a um bot
`team_id`	`integer`	Nao	ID da equipe. Usado quando assignee_id não é enviado.

Atribuição por agente OU equipe

Envie assignee_id para atribuir a um agente, OU team_id para atribuir a uma equipe. Se assignee_id estiver presente, ele tem prioridade.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/assignments" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "assignee_id": 5 }'

Resumo por IA

GET/api/v1/accounts/{account_id}/conversations/{conversation_id}/summary

Retorna o resumo da conversa gerado por IA (quando já existe) e o horário da geração. Não dispara geração.

200Resumo armazenado (summary e summary_generated_at são null quando nenhum resumo foi gerado ainda)

json

{
  "summary": "Cliente relatou falha no pagamento e foi orientado a refazer a compra.",
  "summary_generated_at": 1718900000
}

POST/api/v1/accounts/{account_id}/conversations/{conversation_id}/summarize

Gera ou regenera o resumo da conversa via Noovi AI nativa e retorna o payload atualizado.

Requer IA configurada

A geração usa a Noovi AI nativa da conta. Se não houver credenciais de IA configuradas, o endpoint responde que a IA está indisponível. Uma falha de geração retorna 422.

bash

curl -X POST "https://chat.seudominio.com/api/v1/accounts/1/conversations/123/summarize" \
  -H "api_access_token: YOUR_TOKEN" \
  -H "Content-Type: application/json"

200Resumo recém-gerado

json

{
  "summary": "Cliente relatou falha no pagamento e foi orientado a refazer a compra.",
  "summary_generated_at": 1718900123
}