Klivo Chat API › Application APIs

Conversas

Liste, crie e gerencie conversas. É o endpoint mais utilizado da API do Klivo Chat.

GET

Listar Conversas

Retorna a lista paginada de conversas. Filtrável por status, agente, equipe e caixa de entrada.

GET
https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations
Parâmetros de Path
account_id integer obrigatório
ID da conta.
Query Parameters
status string
Status: open, resolved, pending, snoozed.
assignee_type string
Tipo: assigned, unassigned, mine, participated.
page integer
Número da página. Padrão: 1.
inbox_id integer
Filtrar por caixa de entrada.
team_id integer
Filtrar por equipe.
labels[] string
Filtrar por label.
CURL 
curl --request GET \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations?status=open&page=1 \
  --header 'api_access_token: '
200 
{
  "data": {
    "meta": {
      "mine_count": 12,
      "unassigned_count": 5,
      "assigned_count": 18,
      "all_count": 35
    },
    "payload": [
      {
        "id": 42,
        "status": "open",
        "inbox_id": 1,
        "contact": { "id": 17, "name": "João Silva" },
        "assignee": { "id": 3, "name": "Maria Agente" },
        "labels": ["urgente"],
        "created_at": 1716000000
      }
    ]
  }
}
POST

Criar Conversa

Cria uma nova conversa para um contato existente.

POST
https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations
Parâmetros de Path
account_id integer obrigatório
ID da conta.
Body Parameters
inbox_id integer obrigatório
ID da caixa de entrada.
contact_id integer obrigatório
ID do contato.
assignee_id integer
ID do agente responsável.
team_id integer
ID da equipe responsável.
status string
Status inicial: open (padrão) ou pending.
additional_attributes object
Atributos extras em formato JSON.
CURL 
curl --request POST \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations \
  --header 'api_access_token: ' \
  --header 'Content-Type: application/json' \
  --data '{
  "inbox_id": 1,
  "contact_id": 17,
  "assignee_id": 3,
  "status": "open"
}'
200 
{
  "id": 43,
  "status": "open",
  "inbox_id": 1,
  "contact": {"id": 17, "name": "João Silva"}
}
GET

Detalhes da Conversa

Retorna todos os dados de uma conversa específica, incluindo mensagens recentes.

GET
https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations/{id}
Parâmetros de Path
account_id integer obrigatório
ID da conta.
id integer obrigatório
ID da conversa.
CURL 
curl --request GET \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations/{id} \
  --header 'api_access_token: '
200 
{
  "id": 42,
  "status": "open",
  "labels": ["urgente"],
  "contact": {"id": 17},
  "messages": [...]
}
PATCH

Atualizar Conversa

Atualiza atributos como status, prioridade e labels de uma conversa.

PATCH
https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations/{id}
Parâmetros de Path
account_id integer obrigatório
ID da conta.
id integer obrigatório
ID da conversa.
Body Parameters
status string
Novo status: open, resolved, pending.
assignee_id integer
ID do novo agente responsável.
team_id integer
ID da nova equipe responsável.
labels array
Array de labels a aplicar.
CURL 
curl --request PATCH \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations/{id} \
  --header 'api_access_token: ' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "resolved",
  "assignee_id": 5
}'
200 
{
  "id": 42,
  "status": "resolved",
  "assignee": {"id": 5}
}
POST

Alternar Status

Alterna o status da conversa entre open e resolved.

POST
https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations/{id}/toggle_status
Parâmetros de Path
account_id integer obrigatório
ID da conta.
id integer obrigatório
ID da conversa.
Body Parameters
status string obrigatório
Status desejado: open, resolved, pending, snoozed.
CURL 
curl --request POST \
  --url https://chat.klivo.marketing/api/v1/accounts/{account_id}/conversations/{id}/toggle_status \
  --header 'api_access_token: ' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "resolved"
}'
200 
{
  "current_status": "resolved",
  "conversation_id": 42
}