{ "openapi": "3.1.0", "info": { "title": "API do NexaChat", "version": "1.1.0", "description": "API pública do NexaChat para integrar o seu sistema: contatos, atendimentos, mensagens, agentes, filas e canais.\n\n**Autenticação:** crie um token em *Integrações → API do NexaChat* e envie `Authorization: Bearer nxk_…`. Cada token pertence a uma empresa e só enxerga os dados dela. Escopos: `read` (GET) e `write` (POST/PATCH).\n\n**Erros:** sempre `{ \"error\": { \"code\", \"message\" } }`.\n\n**Limite:** 300 requisições por minuto por token (cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; ao exceder, 429 com `Retry-After`).\n\n**Paginação:** por cursor (`limit` + `cursor`); listas devolvem `data`, `has_more` e `next_cursor`.\n\n**Idempotência:** envie `Idempotency-Key` nos POST para poder repetir com segurança.\n\n**Auditoria:** toda ação de escrita feita pela API fica no histórico da empresa com o nome do token.\n\n**Webhooks:** o NexaChat também avisa o seu sistema quando algo acontece (seção *Webhooks*): cabeçalhos `X-NexaChat-Event` e `X-NexaChat-Signature` (HMAC-SHA256), reenvio automático e o campo `test`.\n\n**Versão e mudanças:** veja o *Histórico de mudanças* no final.", "x-changelog": [ { "version": "1.1.0", "date": "2026-10-02", "changes": [ "Webhooks documentados na especificação (seção `webhooks`): cabeçalhos, assinatura HMAC-SHA256, política de reenvio e o campo `test`.", "Eventos novos: `quality.generated`, `lead.created`, `lead.stage_changed`, `invoice.paid`, `call.received`, `call.missed`.", "Mensagem: novos campos `channel` e `transcript` (texto do áudio) e valores documentados de `delivery_status` (sent, delivered, read, failed).", "Atendimento: novos campos `tags`, `department` e `quality` (Nota de Qualidade, somente leitura).", "Evento `message.received` de áudio passa a trazer `transcript`." ] }, { "version": "1.0.0", "date": "2026-09-30", "changes": [ "Primeira versão pública: contatos, atendimentos, mensagens, agentes, filas e canais; tokens com escopo; paginação por cursor; Idempotency-Key; limite de 300 requisições por minuto." ] } ], "x-legacy": "A API antiga `/api/ext` (token único; `/api/ext/contacts`, `/api/ext/conversations`, `/api/ext/messages`) continua funcionando por compatibilidade, mas não recebe novidades. Para integrações novas use a API v1 (`/api/v1`)." }, "servers": [ { "url": "/api/v1", "description": "Este servidor" } ], "tags": [ { "name": "Conta", "description": "Informações do token." }, { "name": "Contatos" }, { "name": "Atendimentos", "description": "Conversas com clientes. Ações: encerrar, transferir, atribuir." }, { "name": "Mensagens" }, { "name": "Equipe e filas", "description": "Agentes, filas (departamentos) e canais, somente leitura." }, { "name": "Webhooks", "description": "Avisos que o NexaChat envia ao seu sistema (POST com JSON). Veja a seção “Webhooks” da documentação para a assinatura (HMAC-SHA256), as novas tentativas e os exemplos." }, { "name": "Telefonia", "description": "Identificação de clientes para a URA do PABX. Exige token com o escopo `telephony`." } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "Token nxk_… criado no painel." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "examples": [ "validation_error" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } } } }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": "string", "description": "Formato internacional, ex.: +5531999998888" }, "email": { "type": "string" }, "notes": { "type": "string" }, "custom": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ContactInput": { "type": "object", "required": [ "name" ], "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "phone": { "type": "string", "maxLength": 30 }, "email": { "type": "string", "format": "email" }, "notes": { "type": "string", "maxLength": 2000 } } }, "ContactPatch": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "phone": { "type": "string", "maxLength": 30 }, "email": { "type": "string" }, "notes": { "type": "string", "maxLength": 2000 } } }, "Conversation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "protocol": { "type": "string", "examples": [ "NX-2026-00000123" ] }, "subject": { "type": "string" }, "channel": { "type": "string", "enum": [ "web", "whatsapp", "telegram", "app", "telephony", "manual", "api" ] }, "status": { "type": "string", "enum": [ "open", "pending", "resolved" ] }, "priority": { "type": "string", "enum": [ "normal", "high" ], "description": "Prioridade do atendimento." }, "contact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid", "description": "Atendente responsável (null = sem responsável)." }, "department_id": { "type": [ "string", "null" ], "format": "uuid" }, "department": { "description": "Departamento (fila) do atendimento.", "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Nomes das etiquetas do atendimento." }, "quality": { "description": "Nota de Qualidade (**somente leitura**), calculada pela IA ao encerrar. null enquanto não houver nota.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Quality" } ] }, "channel_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "first_response_at": { "type": [ "string", "null" ], "format": "date-time" }, "closed_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "Quality": { "type": "object", "description": "Nota de Qualidade do atendimento (somente leitura).", "properties": { "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 10, "description": "Nota final de 0 a 10 (já com ajuste do gestor, se houver)." }, "handler": { "type": "string", "enum": [ "human", "ai", "mixed", "" ] }, "category": { "type": "string" }, "summary": { "type": "string" }, "resolved_first_contact": { "type": [ "boolean", "null" ] }, "tone": { "type": "string" }, "evaluated_at": { "type": "string", "format": "date-time" } } }, "ConversationCreate": { "type": "object", "additionalProperties": false, "description": "Informe contact_id **ou** phone (o contato é criado se não existir).", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "phone": { "type": "string" }, "name": { "type": "string", "description": "Nome, se o contato for criado." }, "subject": { "type": "string", "default": "Atendimento via API" }, "message": { "type": "string", "maxLength": 5000, "description": "Primeira mensagem, registrada como do cliente." }, "department_id": { "type": "string", "format": "uuid", "description": "Fila de destino." } } }, "Message": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "incoming", "outgoing", "note", "system" ] }, "body": { "type": "string" }, "author_id": { "type": [ "string", "null" ], "format": "uuid" }, "delivery_status": { "type": [ "string", "null" ], "enum": [ "sent", "delivered", "read", "failed", null ], "description": "Entrega da mensagem enviada pelo WhatsApp/Telegram: `sent` (saiu), `delivered` (chegou ao aparelho), `read` (lida) ou `failed` (falhou). null quando o canal não informa." }, "channel": { "type": [ "string", "null" ], "enum": [ "web", "whatsapp", "telegram", "app", "telephony", "manual", "api", null ], "description": "Canal do atendimento a que a mensagem pertence." }, "transcript": { "description": "Transcrição do áudio do cliente (quando o motor de voz está ligado). null em mensagens sem áudio.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Transcript" } ] }, "created_at": { "type": "string", "format": "date-time" } } }, "Transcript": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "done", "unclear", "error" ], "description": "`done` = transcrito; `unclear` = áudio vazio ou com muito ruído; `error` = o motor de voz falhou." }, "text": { "type": "string", "description": "Texto falado (vazio se não foi transcrito)." }, "confidence": { "type": [ "number", "null" ], "minimum": 0, "maximum": 1 }, "seconds": { "type": [ "integer", "null" ], "description": "Duração do áudio, em segundos." }, "truncated": { "type": "boolean", "description": "true se só o começo do áudio foi transcrito (limite de duração)." }, "engine": { "type": "string" } } }, "WebhookEnvelope": { "type": "object", "required": [ "event", "data", "timestamp" ], "properties": { "event": { "type": "string" }, "data": { "type": "object" }, "timestamp": { "type": "string", "format": "date-time" }, "test": { "type": "boolean", "const": true, "description": "Presente (true) só em avisos de TESTE: conversa do Simulador com a opção “disparar webhooks” ligada. O cabeçalho `X-NexaChat-Test: 1` acompanha." } } }, "MessageCreate": { "type": "object", "required": [ "body" ], "additionalProperties": false, "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "outgoing", "note", "incoming" ], "default": "outgoing", "description": "outgoing = resposta ao cliente pelo canal; note = nota interna; incoming = mensagem do cliente relatada pelo seu sistema." } } }, "Agent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "owner", "admin", "agent" ] }, "availability": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Queue": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "agent_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "created_at": { "type": "string", "format": "date-time" } } }, "Channel": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "web", "whatsapp", "telegram", "app" ] }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } } }, "responses": { "BadRequest": { "description": "Dados inválidos (validation_error, invalid_json…).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Token ausente, inválido, expirado ou revogado (unauthorized).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Sem o escopo necessário (insufficient_scope) ou conta desativada.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Não encontrado — inclusive ids de outra empresa (not_found).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Conflito, ex.: contato já existe (conflict, com details.existing_id).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IdempotencyReuse": { "description": "Idempotency-Key já usada com outro corpo (idempotency_key_reuse).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Limite de requisições (rate_limited).", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos até poder tentar de novo." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/telephony/identify": { "get": { "tags": [ "Telefonia" ], "summary": "Identificar cliente (URA)", "description": "Usado pelo dialplan do PABX. Informe `phone` (número de quem liga) **ou** `document` (CPF/CNPJ digitado na URA, só números). Exige token com o escopo `telephony`. A resposta é enxuta de propósito: nunca traz CPF, endereço, e-mail, valores nem o nome completo. Limite: 120 consultas/min por token; cada consulta é auditada.", "security": [ { "bearer": [] } ], "operationId": "identifyCaller", "parameters": [ { "name": "phone", "in": "query", "schema": { "type": "string", "maxLength": 30 }, "description": "Número de quem liga, ex.: 11988887777 ou +5511988887777." }, { "name": "document", "in": "query", "schema": { "type": "string", "maxLength": 20 }, "description": "CPF (11) ou CNPJ (14), só números." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "found": { "type": "boolean" }, "first_name": { "type": "string" }, "contract_status": { "type": "string" }, "blocked": { "type": "boolean" }, "overdue": { "type": "boolean", "description": "Tem fatura vencida." }, "maintenance": { "type": "boolean", "description": "Afetado por manutenção na região." }, "suggested_queue": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/me": { "get": { "tags": [ "Conta" ], "summary": "Dados do token", "description": "Mostra o nome, escopos e validade do token e o limite de requisições.", "security": [ { "bearer": [] } ], "operationId": "getMe", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "token": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "company": { "type": "object", "properties": { "name": { "type": "string" } } }, "rate_limit": { "type": "object", "properties": { "limit": { "type": "integer" }, "window_seconds": { "type": "integer" } } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts": { "get": { "tags": [ "Contatos" ], "summary": "Listar contatos", "description": "Mais recentes primeiro.", "security": [ { "bearer": [] } ], "operationId": "listContacts", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Itens por página (1 a 200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor devolvido em next_cursor." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca por nome, telefone ou e-mail." }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Telefone exato (qualquer formato; é normalizado)." }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "E-mail exato." }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados a partir de (ISO 8601 ou só a data, ex.: 2026-09-01)." }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados até (com só a data, inclui o dia inteiro)." } ], "responses": { "200": { "description": "Página de contatos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Envie em ?cursor= para a próxima página. Nulo na última página." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Contatos" ], "summary": "Criar contato", "description": "Se já existir contato com o mesmo telefone ou e-mail, responde 409 com `error.details.existing_id`.", "security": [ { "bearer": [] } ], "operationId": "createContact", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" }, "example": { "name": "Maria Souza", "phone": "+5531999998888", "email": "maria@exemplo.com.br" } } } }, "responses": { "201": { "description": "Criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/contacts/{id}": { "get": { "tags": [ "Contatos" ], "summary": "Buscar contato", "description": "", "security": [ { "bearer": [] } ], "operationId": "getContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do contato" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Contatos" ], "summary": "Alterar contato", "description": "Só os campos enviados são alterados.", "security": [ { "bearer": [] } ], "operationId": "updateContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do contato" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactPatch" }, "example": { "notes": "Cliente VIP" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Contact" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/conversations": { "get": { "tags": [ "Atendimentos" ], "summary": "Listar atendimentos", "description": "Mais recentes primeiro.", "security": [ { "bearer": [] } ], "operationId": "listConversations", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Itens por página (1 a 200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor devolvido em next_cursor." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "pending", "resolved" ] }, "description": "Situação." }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "web", "whatsapp", "telegram", "instagram", "manual", "api", "app" ] }, "description": "Canal de origem." }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Id do atendente, ou `none` para sem responsável." }, { "name": "department_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Fila." }, { "name": "contact_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Contato." }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados a partir de (ISO 8601 ou só a data, ex.: 2026-09-01)." }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados até (com só a data, inclui o dia inteiro)." }, { "name": "updated_since", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Alterados desde (ISO 8601) — útil para sincronizar." } ], "responses": { "200": { "description": "Página de atendimentos.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Envie em ?cursor= para a próxima página. Nulo na última página." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Atendimentos" ], "summary": "Abrir atendimento", "description": "", "security": [ { "bearer": [] } ], "operationId": "createConversation", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationCreate" }, "example": { "phone": "+5531999998888", "name": "Maria Souza", "subject": "Segunda via da fatura", "message": "Preciso da segunda via." } } } }, "responses": { "201": { "description": "Criado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/conversations/{id}": { "get": { "tags": [ "Atendimentos" ], "summary": "Buscar atendimento", "description": "", "security": [ { "bearer": [] } ], "operationId": "getConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do atendimento" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/conversations/{id}/close": { "post": { "tags": [ "Atendimentos" ], "summary": "Encerrar atendimento", "description": "", "security": [ { "bearer": [] } ], "operationId": "closeConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do atendimento" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "responses": { "200": { "description": "Encerrado.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/conversations/{id}/assign": { "post": { "tags": [ "Atendimentos" ], "summary": "Atribuir a um atendente", "description": "Use `user_id: null` para tirar o responsável. Ao atribuir, o robô do fluxo para de responder.", "security": [ { "bearer": [] } ], "operationId": "assignConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do atendimento" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id" ], "additionalProperties": false, "properties": { "user_id": { "type": [ "string", "null" ], "format": "uuid" } } }, "example": { "user_id": "00000000-0000-0000-0000-000000000000" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/conversations/{id}/transfer": { "post": { "tags": [ "Atendimentos" ], "summary": "Transferir", "description": "Para uma fila (`to_department`), para um atendente (`to_user`) ou ambos. Registra uma nota interna.", "security": [ { "bearer": [] } ], "operationId": "transferConversation", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do atendimento" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "to_user": { "type": [ "string", "null" ], "format": "uuid" }, "to_department": { "type": [ "string", "null" ], "format": "uuid" }, "note": { "type": "string", "maxLength": 1000 } } }, "example": { "to_department": "00000000-0000-0000-0000-000000000000", "note": "Cliente pediu o financeiro" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Conversation" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/conversations/{id}/messages": { "get": { "tags": [ "Mensagens" ], "summary": "Listar mensagens do atendimento", "description": "Por padrão, as mais recentes primeiro; use `order=asc` para ordem cronológica.", "security": [ { "bearer": [] } ], "operationId": "listConversationMessages", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do atendimento" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Itens por página (1 a 200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor devolvido em next_cursor." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Ordem." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "incoming", "outgoing", "note", "system" ] }, "description": "Tipo." }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados a partir de (ISO 8601 ou só a data, ex.: 2026-09-01)." }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados até (com só a data, inclui o dia inteiro)." } ], "responses": { "200": { "description": "Página de mensagens.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Envie em ?cursor= para a próxima página. Nulo na última página." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Mensagens" ], "summary": "Enviar mensagem no atendimento", "description": "`kind: outgoing` (padrão) envia ao cliente pelo canal do atendimento. No WhatsApp oficial, fora da janela de 24 h responde 409 `whatsapp_window_closed`.", "security": [ { "bearer": [] } ], "operationId": "createConversationMessage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id do atendimento" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageCreate" }, "example": { "body": "Olá! Sua fatura foi enviada por e-mail." } } } }, "responses": { "201": { "description": "Criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/messages": { "get": { "tags": [ "Mensagens" ], "summary": "Listar mensagens", "description": "Todas as mensagens da empresa, com filtros.", "security": [ { "bearer": [] } ], "operationId": "listMessages", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Itens por página (1 a 200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor devolvido em next_cursor." }, { "name": "conversation_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Atendimento." }, { "name": "order", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" }, "description": "Ordem." }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "incoming", "outgoing", "note", "system" ] }, "description": "Tipo." }, { "name": "created_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados a partir de (ISO 8601 ou só a data, ex.: 2026-09-01)." }, { "name": "created_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados até (com só a data, inclui o dia inteiro)." } ], "responses": { "200": { "description": "Página de mensagens.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Envie em ?cursor= para a próxima página. Nulo na última página." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Mensagens" ], "summary": "Criar mensagem", "description": "Igual a enviar no atendimento, com `conversation_id` no corpo.", "security": [ { "bearer": [] } ], "operationId": "createMessage", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "conversation_id", "body" ], "additionalProperties": false, "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "body": { "type": "string", "maxLength": 5000 }, "kind": { "type": "string", "enum": [ "outgoing", "note", "incoming" ], "default": "outgoing" } } }, "example": { "conversation_id": "00000000-0000-0000-0000-000000000000", "body": "Olá!" } } } }, "responses": { "201": { "description": "Criada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/messages/template": { "post": { "tags": [ "Mensagens" ], "summary": "Enviar template do WhatsApp Oficial", "description": "Envia um **template aprovado pela Meta** (o único tipo de mensagem permitido fora da janela de 24 h). O cliente é achado pelo telefone (`to`), por `contact_id` ou por `conversation_id`; o número oficial, por `channel_id` (se omitido, usa o primeiro ativo). `variables` pode ser uma **lista** (na ordem de {{1}}, {{2}}…) ou um **objeto** com os nomes configurados no template (ex.: `nome`, `fatura_valor`). Templates de MARKETING não são enviados a quem respondeu SAIR (403). Cada envio é registrado com a categoria (custo). Use `reference` para evitar duplicados.", "security": [ { "bearer": [] } ], "operationId": "sendTemplateMessage", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Chave única (até 200 caracteres ASCII). Repetir a mesma chave com o mesmo corpo devolve a resposta original (cabeçalho Idempotent-Replay: true) sem criar de novo; com outro corpo, 422." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template" ], "additionalProperties": false, "properties": { "to": { "type": "string", "description": "Telefone do cliente com DDD (ex.: 81999998888)." }, "contact_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "channel_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "Nome, usado só se o contato for criado agora." }, "template": { "type": "string", "description": "Nome do template (ex.: fatura_disponivel)." }, "language": { "type": "string", "example": "pt_BR" }, "variables": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "string" } } ] }, "header_text": { "type": "string" }, "header_media_url": { "type": "string", "format": "uri" }, "url_suffix": { "type": "array", "items": { "type": "string" }, "maxItems": 2 }, "copy_code": { "type": "string", "maxLength": 15 }, "code": { "type": "string", "description": "Código (templates de autenticação)." }, "reference": { "type": "string", "maxLength": 200, "description": "Identificador único do seu lado; repetir é ignorado (409)." } } }, "example": { "to": "81999998888", "template": "fatura_disponivel", "variables": [ "Maria", "99,90", "10/11/2026", "34191.79001...", "00020126..." ] } } } }, "responses": { "201": { "description": "Enfileirada.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "message_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": "string", "format": "uuid" }, "channel_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "queued" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/IdempotencyReuse" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/messages/{id}": { "get": { "tags": [ "Mensagens" ], "summary": "Buscar mensagem", "description": "", "security": [ { "bearer": [] } ], "operationId": "getMessage", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Id da mensagem" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Message" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/agents": { "get": { "tags": [ "Equipe e filas" ], "summary": "Listar agentes", "description": "", "security": [ { "bearer": [] } ], "operationId": "listAgents", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Itens por página (1 a 200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor devolvido em next_cursor." } ], "responses": { "200": { "description": "Página de agentes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Envie em ?cursor= para a próxima página. Nulo na última página." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/queues": { "get": { "tags": [ "Equipe e filas" ], "summary": "Listar filas", "description": "Filas são os departamentos do painel.", "security": [ { "bearer": [] } ], "operationId": "listQueues", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Itens por página (1 a 200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor devolvido em next_cursor." } ], "responses": { "200": { "description": "Página de filas.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Queue" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Envie em ?cursor= para a próxima página. Nulo na última página." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/channels": { "get": { "tags": [ "Equipe e filas" ], "summary": "Listar canais", "description": "Sem chaves nem configurações internas.", "security": [ { "bearer": [] } ], "operationId": "listChannels", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 }, "description": "Itens por página (1 a 200)." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Cursor devolvido em next_cursor." } ], "responses": { "200": { "description": "Página de canais.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Channel" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Envie em ?cursor= para a próxima página. Nulo na última página." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "webhooks": { "ping": { "post": { "tags": [ "Webhooks" ], "summary": "Teste do webhook", "description": "Enviado quando você clica em **Enviar teste** no painel. Serve para validar o endereço e a assinatura.", "operationId": "webhook_ping", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "ping" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "ping" }, "data": { "type": "object", "properties": { "message": { "type": "string" }, "by": { "type": "string", "description": "Quem pediu o teste." } } } } } ] }, "example": { "event": "ping", "data": { "message": "Teste de webhook do NexaChat", "by": "Maria" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "conversation.opened": { "post": { "tags": [ "Webhooks" ], "summary": "Atendimento aberto", "description": "Um atendimento novo foi criado (mensagem de cliente, chat do site, API…).", "operationId": "webhook_conversation_opened", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "conversation.opened" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "conversation.opened" }, "data": { "type": "object", "required": [ "conversation_id" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "protocol": { "type": "string" }, "contact_id": { "type": "string", "format": "uuid" }, "channel": { "type": "string", "description": "Presente quando o atendimento nasce de um canal." } } } } } ] }, "example": { "event": "conversation.opened", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001", "protocol": "NX-2026-00000123", "contact_id": "00000000-0000-0000-0000-000000000002" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "conversation.assumed": { "post": { "tags": [ "Webhooks" ], "summary": "Atendimento assumido", "description": "Um atendente assumiu (ou recebeu) o atendimento; o robô para.", "operationId": "webhook_conversation_assumed", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "conversation.assumed" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "conversation.assumed" }, "data": { "type": "object", "required": [ "conversation_id" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "assigned_to": { "type": "string", "format": "uuid" } } } } } ] }, "example": { "event": "conversation.assumed", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001", "assigned_to": "00000000-0000-0000-0000-000000000003" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "conversation.transferred": { "post": { "tags": [ "Webhooks" ], "summary": "Atendimento transferido", "description": "O atendimento foi transferido para outro atendente e/ou departamento.", "operationId": "webhook_conversation_transferred", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "conversation.transferred" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "conversation.transferred" }, "data": { "type": "object", "required": [ "conversation_id" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "to_user": { "type": [ "string", "null" ], "format": "uuid" }, "to_department": { "type": [ "string", "null" ], "format": "uuid" } } } } } ] }, "example": { "event": "conversation.transferred", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001", "to_user": null, "to_department": "00000000-0000-0000-0000-000000000004" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "conversation.closed": { "post": { "tags": [ "Webhooks" ], "summary": "Atendimento encerrado", "description": "O atendimento foi encerrado.", "operationId": "webhook_conversation_closed", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "conversation.closed" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "conversation.closed" }, "data": { "type": "object", "required": [ "conversation_id" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" } } } } } ] }, "example": { "event": "conversation.closed", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "message.received": { "post": { "tags": [ "Webhooks" ], "summary": "Mensagem recebida", "description": "O cliente enviou uma mensagem. Em mensagens de **áudio**, o campo `transcript` traz o texto falado (quando há motor de voz).", "operationId": "webhook_message_received", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "message.received" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "message.received" }, "data": { "type": "object", "required": [ "conversation_id", "message_id", "body" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "body": { "type": "string" }, "transcript": { "description": "Só em áudio.", "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Transcript" } ] } } } } } ] }, "example": { "event": "message.received", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001", "message_id": "00000000-0000-0000-0000-000000000002", "body": "Preciso da segunda via da fatura" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "message.sent": { "post": { "tags": [ "Webhooks" ], "summary": "Mensagem enviada", "description": "Um atendente (ou a API) enviou uma mensagem ao cliente. O status de entrega aparece depois em `delivery_status` da mensagem (consulte `GET /messages/{id}`).", "operationId": "webhook_message_sent", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "message.sent" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "message.sent" }, "data": { "type": "object", "required": [ "conversation_id", "message_id", "body" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "message_id": { "type": "string", "format": "uuid" }, "body": { "type": "string" } } } } } ] }, "example": { "event": "message.sent", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001", "message_id": "00000000-0000-0000-0000-000000000002", "body": "Enviei a fatura por aqui." }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "contact.created": { "post": { "tags": [ "Webhooks" ], "summary": "Contato criado", "description": "Um contato novo foi cadastrado.", "operationId": "webhook_contact_created", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "contact.created" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "contact.created" }, "data": { "type": "object", "required": [ "contact_id" ], "properties": { "contact_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } } } } ] }, "example": { "event": "contact.created", "data": { "contact_id": "00000000-0000-0000-0000-000000000002", "name": "Maria Souza", "phone": "+5531999998888", "email": "maria@exemplo.com.br" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "contact.updated": { "post": { "tags": [ "Webhooks" ], "summary": "Contato atualizado", "description": "Os dados de um contato foram alterados.", "operationId": "webhook_contact_updated", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "contact.updated" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "contact.updated" }, "data": { "type": "object", "required": [ "contact_id" ], "properties": { "contact_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } } } } ] }, "example": { "event": "contact.updated", "data": { "contact_id": "00000000-0000-0000-0000-000000000002", "name": "Maria Souza", "phone": "+5531999998888", "email": "maria@exemplo.com.br" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "csat.received": { "post": { "tags": [ "Webhooks" ], "summary": "Avaliação (CSAT) recebida", "description": "O cliente avaliou o atendimento (nota de 1 a 5).", "operationId": "webhook_csat_received", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "csat.received" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "csat.received" }, "data": { "type": "object", "required": [ "conversation_id", "rating" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "comment": { "type": [ "string", "null" ] } } } } } ] }, "example": { "event": "csat.received", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001", "rating": 5, "comment": "Atendimento rápido!" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "quality.generated": { "post": { "tags": [ "Webhooks" ], "summary": "Nota de Qualidade gerada", "description": "A IA avaliou um atendimento encerrado (nota de 0 a 10). Só existe se a Nota de Qualidade estiver ligada.", "operationId": "webhook_quality_generated", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "quality.generated" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "quality.generated" }, "data": { "type": "object", "required": [ "conversation_id", "score" ], "properties": { "conversation_id": { "type": "string", "format": "uuid" }, "score": { "type": "number", "minimum": 0, "maximum": 10 }, "handler": { "type": "string", "enum": [ "human", "ai", "mixed" ] }, "category": { "type": "string" }, "summary": { "type": "string" }, "agent_id": { "type": [ "string", "null" ], "format": "uuid" } } } } } ] }, "example": { "event": "quality.generated", "data": { "conversation_id": "00000000-0000-0000-0000-000000000001", "score": 8.5, "handler": "human", "category": "financeiro", "summary": "Cliente pediu a 2ª via e foi atendido com clareza.", "agent_id": "00000000-0000-0000-0000-000000000003" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "lead.created": { "post": { "tags": [ "Webhooks" ], "summary": "Lead criado (CRM)", "description": "Um lead novo entrou no funil (criado pela equipe, pelo Vendedor de IA ou pelo site).", "operationId": "webhook_lead_created", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "lead.created" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "lead.created" }, "data": { "type": "object", "required": [ "lead_id", "title", "stage" ], "properties": { "lead_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "value": { "type": "number" }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } } } } ] }, "example": { "event": "lead.created", "data": { "lead_id": "00000000-0000-0000-0000-000000000001", "title": "Lead IA — Maria Souza — Fibra 400 Mega", "value": 0, "stage": { "id": "00000000-0000-0000-0000-000000000002", "name": "Novo" }, "contact_id": "00000000-0000-0000-0000-000000000003", "assigned_to": null, "created_at": "2026-10-02T12:00:00.000Z" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "lead.stage_changed": { "post": { "tags": [ "Webhooks" ], "summary": "Lead mudou de etapa", "description": "Um lead foi movido para outra etapa do funil.", "operationId": "webhook_lead_stage_changed", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "lead.stage_changed" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "lead.stage_changed" }, "data": { "type": "object", "required": [ "lead_id", "title", "stage", "previous_stage" ], "properties": { "lead_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "value": { "type": "number" }, "stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "previous_stage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "assigned_to": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } } } } } ] }, "example": { "event": "lead.stage_changed", "data": { "lead_id": "00000000-0000-0000-0000-000000000001", "title": "Lead IA — Maria Souza — Fibra 400 Mega", "value": 0, "stage": { "id": "00000000-0000-0000-0000-000000000002", "name": "Proposta" }, "previous_stage": { "id": "00000000-0000-0000-0000-000000000003", "name": "Qualificado" }, "contact_id": "00000000-0000-0000-0000-000000000004", "assigned_to": null, "created_at": "2026-10-02T12:00:00.000Z" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "invoice.paid": { "post": { "tags": [ "Webhooks" ], "summary": "Fatura paga", "description": "O NexaChat percebeu a baixa de uma fatura do assinante no ERP (conferência periódica, PIX pelo app ou régua de cobrança). Avisa **uma vez por fatura**.", "operationId": "webhook_invoice_paid", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "invoice.paid" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "invoice.paid" }, "data": { "type": "object", "required": [ "invoice_id", "amount", "paid_at" ], "properties": { "invoice_id": { "type": "string" }, "contract_id": { "type": [ "string", "null" ] }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "amount": { "type": "number" }, "due_date": { "type": [ "string", "null" ], "format": "date" }, "paid_at": { "type": "string", "format": "date-time" }, "source": { "type": "string", "enum": [ "erp", "pix_app", "regua" ] } } } } } ] }, "example": { "event": "invoice.paid", "data": { "invoice_id": "12345", "contract_id": "678", "contact_id": "00000000-0000-0000-0000-000000000001", "amount": 99.9, "due_date": "2026-09-25", "paid_at": "2026-10-02T12:00:00.000Z", "source": "erp" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "call.received": { "post": { "tags": [ "Webhooks" ], "summary": "Chamada recebida", "description": "Uma ligação de entrada chegou (telefonia ligada).", "operationId": "webhook_call_received", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "call.received" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "call.received" }, "data": { "type": "object", "required": [ "call_id", "direction" ], "properties": { "call_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "queue": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] } } } } } ] }, "example": { "event": "call.received", "data": { "call_id": "00000000-0000-0000-0000-000000000001", "conversation_id": "00000000-0000-0000-0000-000000000002", "direction": "inbound", "from": "5531999998888", "to": "3133334444", "status": "ringing", "contact_id": "00000000-0000-0000-0000-000000000003", "queue": "suporte", "extension": null, "duration_seconds": null }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } }, "call.missed": { "post": { "tags": [ "Webhooks" ], "summary": "Chamada perdida", "description": "Uma ligação de entrada terminou sem ser atendida.", "operationId": "webhook_call_missed", "parameters": [ { "name": "X-NexaChat-Event", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Nome do evento.", "example": "call.missed" }, { "name": "X-NexaChat-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`sha256=` + HMAC-SHA256 hexadecimal do **corpo bruto**, com o segredo do webhook.", "example": "sha256=3b1f…" }, { "name": "X-NexaChat-Test", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "1" ] }, "description": "Só nos avisos de teste (`test: true` no corpo)." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "event": { "const": "call.missed" }, "data": { "type": "object", "required": [ "call_id", "direction" ], "properties": { "call_id": { "type": "string", "format": "uuid" }, "conversation_id": { "type": [ "string", "null" ], "format": "uuid" }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "contact_id": { "type": [ "string", "null" ], "format": "uuid" }, "queue": { "type": [ "string", "null" ] }, "extension": { "type": [ "string", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] }, "result": { "type": [ "string", "null" ] } } } } } ] }, "example": { "event": "call.missed", "data": { "call_id": "00000000-0000-0000-0000-000000000001", "conversation_id": "00000000-0000-0000-0000-000000000002", "direction": "inbound", "from": "5531999998888", "to": "3133334444", "status": "missed", "contact_id": "00000000-0000-0000-0000-000000000003", "queue": "suporte", "extension": null, "duration_seconds": null, "result": "noanswer" }, "timestamp": "2026-10-02T12:00:00.000Z" } } } }, "responses": { "200": { "description": "Responda com qualquer código **2xx** em até 10 segundos para confirmar. Qualquer outra resposta (ou demora) agenda nova tentativa." } } } } } }