Conversas

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

Todos os endpoints exigem duas credenciais: o campo embedKey no corpo (chave de embed do canal) e o header X-Client-Token. As duas precisam pertencer ao mesmo canal e podem ser rotacionadas de forma independente. 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
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`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 '{
    "embedKey": "emb_xxxxxxxx",
    "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
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`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 '{
    "embedKey": "emb_xxxxxxxx",
    "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
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`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 '{
    "embedKey": "emb_xxxxxxxx",
    "phone": "5511999999999",
    "note": "Cliente solicitou retorno em 3 dias úteis."
  }'

Resposta

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

Atendimento vinculado a um registro externo (card)

Quatro endpoints permitem amarrar o ciclo de atendimento a um identificador de outro sistema (card de CRM, chamado, pedido). O identificador é gravado em externalRef e a origem em externalSource.

Todos os endpoints deste grupo — inclusive os de card — exigem o phone do contato. O identificador do card sozinho ainda não abre nem encerra atendimento.

Autenticação: embedKey no corpo + header X-Client-Token, em todas as rotas — inclusive nas automações do card. Chamadas com apenas uma das credenciais ainda funcionam durante a transição, mas a resposta traz o campo deprecation avisando que o par passará a ser obrigatório.

Abrir atendimento

POST /conversations-api/abrir

Abre um atendimento já gravando o identificador do card. Se o contato já tiver um atendimento aberto, o endpoint apenas vincula o card a ele e responde created: false.

Campo	Tipo	Obrigatório	Descrição
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`phone`	string	✅	Número do contato
`externalRef`	string	✅	Identificador do card no sistema externo
`externalSource`	string	❌	Origem do identificador (ex.: `pipefy`, `crm`)

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/abrir" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "embedKey": "emb_xxxxxxxx",
    "phone": "5511999999999",
    "externalRef": "card-12345",
    "externalSource": "pipefy"
  }'

{
  "success": true,
  "conversationId": "uuid",
  "contactId": "uuid",
  "created": true,
  "externalRef": "card-12345",
  "openedAt": "2026-09-21T11:40:00.000Z"
}

Vincular card a um atendimento aberto

POST /conversations-api/vincular

Amarra um card a um atendimento já aberto. Se o identificador já pertencer a outro atendimento, devolve o existente com linked: false. Sem atendimento aberto, responde 404.

Campo	Tipo	Obrigatório	Descrição
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`phone`	string	✅	Número do contato
`externalRef`	string	✅	Identificador do card
`externalSource`	string	❌	Origem do identificador

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/vincular" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "embedKey": "emb_xxxxxxxx",
    "phone": "5511999999999",
    "externalRef": "card-12345",
    "externalSource": "pipefy"
  }'

{
  "success": true,
  "conversationId": "uuid",
  "contactId": "uuid",
  "linked": true
}

Fechar atendimento

POST /conversations-api/fechar

Encerra o atendimento aberto do contato e também fecha a fila do chat, mantendo painel e API coerentes. Informe externalRef para encerrar apenas o atendimento daquele card. Sem atendimento aberto, responde 404.

Campo	Tipo	Obrigatório	Descrição
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`phone`	string	✅	Número do contato
`externalRef`	string	❌	Encerra somente o atendimento com este identificador
`closeReason`	string	❌	Motivo do encerramento

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/fechar" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "embedKey": "emb_xxxxxxxx",
    "phone": "5511999999999",
    "externalRef": "card-12345",
    "closeReason": "Pedido concluído"
  }'

{
  "success": true,
  "conversationId": "uuid",
  "contactId": "uuid"
}

Encerrar pela automação do card

POST /conversations-api/encerrar-por-card

Feito para a fase final do card: exige embedKey + X-Client-Token e é idempotente — se o card já estiver encerrado (ou nunca tiver tido atendimento aberto), responde 200 com alreadyClosed: true em vez de erro.

Campo	Tipo	Obrigatório	Descrição
`phone`	string	✅	Número do contato
`externalRef`	string	✅	Identificador do card
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`closeReason`	string	❌	Motivo do encerramento

Envie sempre embedKey no corpo e X-Client-Token no header.

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/encerrar-por-card" \
  -H "Content-Type: application/json" \
  -d '{
    "embedKey": "emb_xxxxxxxx",
    "phone": "5511999999999",
    "externalRef": "card-12345",
    "closeReason": "Card movido para a fase final"
  }'

{
  "success": true,
  "conversationId": "uuid",
  "contactId": "uuid",
  "alreadyClosed": false
}

Buscar atendimentos do contato

POST /conversations-api/buscar

Lista os atendimentos do contato, do mais recente para o mais antigo. Informe externalRef para filtrar por card.

Campo	Tipo	Obrigatório	Descrição
`embedKey`	string	✅	Chave de embed do canal (`emb_...`)
`phone`	string	✅	Número do contato
`externalRef`	string	❌	Filtra pelos atendimentos deste card
`limit`	number	❌	Máximo de registros (padrão `20`, teto `100`)

curl -X POST "https://wapi.stegia.com.br/functions/v1/conversations-api/buscar" \
  -H "Content-Type: application/json" \
  -H "X-Client-Token: SEU_TOKEN" \
  -d '{
    "embedKey": "emb_xxxxxxxx",
    "phone": "5511999999999",
    "limit": 10
  }'

{
  "success": true,
  "contactId": "uuid",
  "conversations": [
    {
      "id": "uuid",
      "status": "closed",
      "opened_at": "2026-09-18T13:02:00.000Z",
      "closed_at": "2026-09-19T09:41:00.000Z",
      "close_reason": "Pedido concluído",
      "external_ref": "card-12345",
      "external_source": "pipefy",
      "message_count": 27,
      "assigned_to": "uuid-do-operador"
    }
  ]
}

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

​Atendimento vinculado a um registro externo (card)

​Abrir atendimento

​Vincular card a um atendimento aberto

​Fechar atendimento

​Encerrar pela automação do card

​Buscar atendimentos do contato

​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

Atendimento vinculado a um registro externo (card)

Abrir atendimento

Vincular card a um atendimento aberto

Fechar atendimento

Encerrar pela automação do card

Buscar atendimentos do contato

Buscar Mensagens (Histórico)

Parâmetros (query string)

Exemplo

Resposta (`format=conversation`)

Comportamentos Automáticos