Conversas

API dedicada para gerenciar atendimentos. Todos os endpoints criam o contato automaticamente se o telefone não existir.

Todos os endpoints requerem o header X-Client-Token. Veja Autenticação.

Base URL

https://wapi.stegia.com.br/functions/v1/conversations-api

Atribuir Operador

POST /conversations-api/assign

Atribui uma conversa a um operador específico. Detecta transferências automaticamente e registra no histórico.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`instanceId`	string	✅	ID da instância
`phone`	string	✅	Número do contato
`assignTo`	string	✅	E-mail ou UUID do operador
`portfolio`	boolean	❌	Se `true`, adiciona à carteira do operador (prioridade absoluta)
`departmentId`	string	❌	UUID do departamento (preserva o atual se omitido)

Exemplo

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/assign" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "assignTo": "joao@empresa.com",
    "portfolio": true
  }'

Resposta

{
  "success": true,
  "contactId": "uuid",
  "assignedTo": "user-uuid",
  "previousAssignedTo": null,
  "portfolio": true,
  "transferred": false,
  "departmentId": null
}

O operador recebe e-mail de notificação automaticamente com link direto para a conversa.
Transferências (quando havia outro operador) são registradas em chat_transfer_log e geram nota interna na conversa.
Com portfolio: true, o contato passa a ser exclusivo do operador na fila.

Mudar Status

POST /conversations-api/status

Altera o status do atendimento (open / closed / pending). Útil para integrar fechamento de tickets em CRMs externos.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`instanceId`	string	✅	ID da instância
`phone`	string	✅	Número do contato
`status`	string	✅	`open`, `closed` ou `pending`
`internalNote`	string	❌	Nota interna registrada junto com a mudança

Exemplo

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/status" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "status": "closed",
    "internalNote": "Ticket resolvido via CRM externo"
  }'

Resposta

{
  "success": true,
  "contactId": "uuid",
  "status": "closed",
  "noteAdded": true
}

Adicionar Nota Interna

POST /conversations-api/note

Adiciona uma nota interna na conversa (não enviada ao cliente, visível apenas para operadores).

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`instanceId`	string	✅	ID da instância
`phone`	string	✅	Número do contato
`note`	string	✅	Conteúdo da nota

Exemplo

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/note" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "instanceId": "SUA_INSTANCIA",
    "phone": "5511999999999",
    "note": "Cliente solicitou retorno em 3 dias úteis."
  }'

Resposta

{
  "success": true,
  "contactId": "uuid",
  "noteId": "uuid-da-nota"
}

Buscar Mensagens (Histórico)

GET /messages-context

Retorna o histórico de mensagens de um contato (telefone) dentro de um intervalo de datas. Útil para exportar conversas, alimentar dashboards externos ou montar contexto para LLMs.

Este endpoint usa a base https://wapi.stegia.com.br/functions/v1/messages-context (não pertence ao grupo conversations-api).

Parâmetros (query string)

Campo	Tipo	Obrigatório	Descrição
`phone`	string	✅	Número do contato (somente dígitos, com DDI)
`start`	string	✅	Data inicial no formato `YYYY-MM-DD`
`end`	string	✅	Data final no formato `YYYY-MM-DD`
`instanceId`	string	✅*	UUID da instância, `instance_id` do WhatsApp Business ou `embed_key` (`emb_...`)
`connectedPhone`	string	✅*	Alternativa a `instanceId`: número conectado da instância
`limit`	number	❌	Máximo de mensagens retornadas (padrão `100`)
`fromMe`	boolean	❌	`true` = só enviadas, `false` = só recebidas, omitido = ambas
`attachments`	boolean	❌	`false` oculta URLs de mídia (padrão `true`)
`format`	string	❌	`conversation` (padrão, formatado para LLM) ou `raw` (linhas brutas)
`includeMeta`	boolean	❌	Inclui `messageId`, `messageType`, `chatName`, etc. (padrão `true`)

* Informe um dos dois: instanceId ou connectedPhone.

Exemplo

curl -X GET "https://wapi.stegia.com.br/functions/v1/messages-context?phone=5511999999999&start=2026-06-01&end=2026-06-15&instanceId=SUA_INSTANCIA&limit=200" \
  -H "X-Client-Token: SEU_TOKEN"

Resposta (`format=conversation`)

{
  "phone": "5511999999999",
  "period": { "start": "2026-06-01", "end": "2026-06-15" },
  "totalMessages": 42,
  "conversation": [
    {
      "role": "user",
      "sender": "João Silva",
      "content": "Olá, gostaria de saber mais sobre o plano.",
      "timestamp": 1718524800,
      "status": "received",
      "messageId": "uuid",
      "messageType": "text",
      "isGroup": false,
      "chatName": null,
      "cardId": null
    },
    {
      "role": "assistant",
      "sender": "Você",
      "content": "Claro! Posso te enviar os detalhes agora.",
      "timestamp": 1718524860,
      "status": "sent"
    }
  ],
  "instanceInfo": {
    "instanceId": "...",
    "zapiInstanceId": "uuid"
  }
}

Use format=raw para receber as mensagens cruas (sem agrupamento role/sender), úteis para data warehouse.

Comportamentos Automáticos

Auto-criação de Contato

Se o phone não existir, o contato é criado com origin: "api" antes de aplicar a operação.

Detecção de Transferência

Quando assign é chamado e a conversa já tem outro operador atribuído, o sistema:

Atualiza para o novo operador
Registra a transferência em chat_transfer_log
Cria nota interna automática com nomes dos operadores envolvidos
Notifica o novo operador por e-mail

Notificação por E-mail

A atribuição via API dispara o mesmo e-mail de notificação enviado quando um operador é atribuído pelo painel — garantindo consistência em qualquer fluxo.

​Conversas

​Base URL

​Atribuir Operador

​Parâmetros

​Exemplo

​Resposta

​Mudar Status

​Parâmetros

​Exemplo

​Resposta

​Adicionar Nota Interna

​Parâmetros

​Exemplo

​Resposta

​Buscar Mensagens (Histórico)

​Parâmetros (query string)

​Exemplo

​Resposta (format=conversation)

​Comportamentos Automáticos

Conversas

Base URL

Atribuir Operador

Parâmetros

Exemplo

Resposta

Mudar Status

Parâmetros

Exemplo

Resposta

Adicionar Nota Interna

Parâmetros

Exemplo

Resposta

Buscar Mensagens (Histórico)

Parâmetros (query string)

Exemplo

Resposta (`format=conversation`)

Comportamentos Automáticos