{"openapi":"3.0.3","info":{"title":"SeuChat API","version":"1.0.0","description":"Use esta API para instalar o widget, identificar clientes pelo seu backend e receber eventos por webhook. Empresa, projetos, atendentes e atendimento são geridos pelo painel do SeuChat."},"servers":[{"url":"/api/v1"}],"tags":[{"name":"Widget","description":"Endpoints usados pelo widget no seu site."},{"name":"Backend do cliente","description":"Endpoints para o servidor da sua aplicação. Nunca exponha a chave secreta no navegador."},{"name":"Webhooks","description":"Configuração de eventos enviados para o seu servidor."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Token da conta administradora, obtido no painel."},"secretKey":{"type":"http","scheme":"bearer","description":"Chave secreta sk_... Use somente no backend da sua aplicação."},"publicKey":{"type":"apiKey","in":"header","name":"x-public-key","description":"Chave pública pk_... usada pelo widget."},"sessionToken":{"type":"http","scheme":"bearer","description":"Token de sessão do visitante ou cliente final."}},"schemas":{"EndUserInput":{"type":"object","required":["id"],"properties":{"id":{"oneOf":[{"type":"string"},{"type":"number"}],"description":"ID do cliente no seu sistema."},"name":{"type":"string","maxLength":120},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":40},"avatarUrl":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true}}},"EndUserUpdate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email"}}},"EndUser":{"type":"object","properties":{"id":{"type":"string","example":"cliente_123"},"name":{"type":"string","nullable":true,"example":"Maria Silva"},"email":{"type":"string","nullable":true,"example":"maria@exemplo.com"}}},"Session":{"type":"object","properties":{"token":{"type":"string","description":"Use como Bearer token no widget.","example":"eyJhbGciOiJIUzI1NiJ9..."},"expiresAt":{"type":"string","format":"date-time"},"projectId":{"type":"string","example":"proj_abc123"},"user":{"$ref":"#/components/schemas/EndUser"}}},"WidgetConfiguration":{"type":"object","properties":{"chatName":{"type":"string","example":"Suporte"},"welcomeMessage":{"type":"string","example":"Olá! Como podemos ajudar?"},"primaryColor":{"type":"string","example":"#635BFF"},"position":{"type":"string","enum":["bottom-right","bottom-left"]},"launcherStyle":{"type":"string","enum":["pill","icon-round","icon-square","custom"]},"buttonText":{"type":"string","example":"Fale conosco"},"theme":{"type":"string","enum":["light","dark"]},"showPoweredBy":{"type":"boolean"}},"additionalProperties":true},"WidgetBootstrap":{"type":"object","properties":{"project":{"type":"object","properties":{"publicId":{"type":"string","example":"proj_abc123"},"name":{"type":"string","example":"Site principal"}}},"widget":{"$ref":"#/components/schemas/WidgetConfiguration"}}},"MessageInput":{"type":"object","required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":4000,"example":"Olá, preciso de ajuda."},"clientMessageId":{"type":"string","maxLength":100,"description":"Identificador único opcional para evitar duplicação.","example":"msg_01HXYZ"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"body":{"type":"string","example":"Olá, preciso de ajuda."},"senderType":{"type":"string","enum":["END_USER","AGENT"]},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"Conversation":{"type":"object","properties":{"id":{"type":"string","example":"conv_abc123"},"status":{"type":"string","enum":["OPEN","PENDING","ASSIGNED","CLOSED"]},"createdAt":{"type":"string","format":"date-time"}},"additionalProperties":true},"PaginatedMessages":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"pageSize":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}},"WebhookInput":{"type":"object","required":["projectId","url","events"],"properties":{"projectId":{"type":"string","example":"proj_abc123"},"url":{"type":"string","format":"uri","example":"https://app.exemplo.com/webhooks/seuchat"},"events":{"type":"array","minItems":1,"items":{"type":"string","enum":["conversation.created","conversation.assigned","conversation.closed","message.created","message.read","user.created"]},"example":["message.created","conversation.closed"]}}},"WebhookUpdate":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["conversation.created","conversation.assigned","conversation.closed","message.created","message.read","user.created"]}},"isActive":{"type":"boolean"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"isActive":{"type":"boolean"},"secret":{"type":"string","description":"O segredo completo só é retornado na criação."}},"additionalProperties":true},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string","example":"Falha de validação"},"requestId":{"type":"string"}}}}}}},"paths":{"/sdk/bootstrap":{"get":{"tags":["Widget"],"summary":"Carregar a configuração do widget","description":"Envie a chave pública no cabeçalho x-public-key. Em chamadas do navegador, o domínio também precisa estar autorizado no projeto.","security":[{"publicKey":[]}],"responses":{"200":{"description":"Configuração do widget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WidgetBootstrap"},"example":{"project":{"publicId":"proj_abc123","name":"Site principal"},"widget":{"chatName":"Suporte","primaryColor":"#635BFF","position":"bottom-right","launcherStyle":"pill","showPoweredBy":true}}}}},"401":{"description":"Chave pública ausente ou inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Origem não autorizada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sdk/session":{"post":{"tags":["Widget"],"summary":"Iniciar uma sessão anônima","description":"Cria um visitante anônimo quando o site não possui login próprio.","security":[{"publicKey":[]}],"responses":{"201":{"description":"Sessão criada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"},"example":{"token":"eyJhbGciOiJIUzI1NiJ9...","expiresAt":"2026-08-02T12:00:00.000Z","user":{"id":"guest_abc123","name":null}}}}},"401":{"description":"Chave pública ausente ou inválida.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sdk/me":{"patch":{"tags":["Widget"],"summary":"Atualizar dados do visitante","security":[{"sessionToken":[]}],"requestBody":{"required":true,"description":"Nome e e-mail coletados no pré-atendimento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUserUpdate"},"example":{"name":"Maria Silva","email":"maria@exemplo.com"}}}},"responses":{"200":{"description":"Dados atualizados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUser"},"example":{"id":"guest_abc123","name":"Maria Silva","email":"maria@exemplo.com"}}}},"401":{"description":"Sessão inválida ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sdk/conversation":{"get":{"tags":["Widget"],"summary":"Obter a conversa atual","security":[{"sessionToken":[]}],"responses":{"200":{"description":"Conversa e mensagens recentes.","content":{"application/json":{"schema":{"type":"object","properties":{"conversation":{"$ref":"#/components/schemas/Conversation"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}}}}}}}},"/sdk/conversation/messages":{"get":{"tags":["Widget"],"summary":"Listar mensagens da conversa atual","security":[{"sessionToken":[]}],"parameters":[{"name":"page","in":"query","description":"Página desejada (padrão: 1).","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","description":"Itens por página.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Mensagens paginadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedMessages"}}}}}},"post":{"tags":["Widget"],"summary":"Enviar uma mensagem","security":[{"sessionToken":[]}],"requestBody":{"required":true,"description":"Conteúdo da mensagem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageInput"},"example":{"body":"Olá, preciso de ajuda.","clientMessageId":"msg_01HXYZ"}}}},"responses":{"201":{"description":"Mensagem criada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}}}}},"/sdk/conversation/read":{"post":{"tags":["Widget"],"summary":"Marcar a conversa como lida","security":[{"sessionToken":[]}],"responses":{"200":{"description":"IDs marcados como lidos.","content":{"application/json":{"schema":{"type":"object","properties":{"readIds":{"type":"array","items":{"type":"string"}}}},"example":{"readIds":["msg_abc123"]}}}}}}},"/sdk/users/token":{"post":{"tags":["Backend do cliente"],"summary":"Identificar cliente e emitir token de sessão","description":"Use no backend após autenticar o seu próprio cliente. O token retornado deve ser passado ao widget como userToken.","security":[{"secretKey":[]}],"requestBody":{"required":true,"description":"Dados do cliente no seu sistema.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUserInput"},"example":{"id":"cliente_123","name":"Maria Silva","email":"maria@exemplo.com","metadata":{"plan":"premium"}}}}},"responses":{"201":{"description":"Cliente salvo e token emitido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"},"example":{"token":"eyJhbGciOiJIUzI1NiJ9...","expiresAt":"2026-08-02T12:00:00.000Z","projectId":"proj_abc123","user":{"id":"cliente_123","name":"Maria Silva","email":"maria@exemplo.com"}}}}}}}},"/sdk/users":{"post":{"tags":["Backend do cliente"],"summary":"Criar ou atualizar um cliente","security":[{"secretKey":[]}],"requestBody":{"required":true,"description":"Dados do cliente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUserInput"},"example":{"id":"cliente_123","name":"Maria Silva","email":"maria@exemplo.com"}}}},"responses":{"200":{"description":"Cliente atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUser"}}}},"201":{"description":"Cliente criado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUser"}}}}}}},"/sdk/users/{externalId}":{"patch":{"tags":["Backend do cliente"],"summary":"Atualizar um cliente identificado","security":[{"secretKey":[]}],"parameters":[{"name":"externalId","in":"path","required":true,"description":"ID do cliente no seu sistema.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Campos que devem ser alterados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUserUpdate"},"example":{"name":"Maria Souza"}}}},"responses":{"200":{"description":"Cliente atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EndUser"}}}},"404":{"description":"Cliente não encontrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sdk/conversations":{"get":{"tags":["Backend do cliente"],"summary":"Consultar conversas do projeto","security":[{"secretKey":[]}],"parameters":[{"name":"page","in":"query","description":"Página desejada (padrão: 1).","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","description":"Itens por página.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"status","in":"query","schema":{"type":"string","enum":["OPEN","PENDING","ASSIGNED","CLOSED"]}},{"name":"search","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Conversas paginadas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"pagination":{"type":"object"}}}}}}}}},"/sdk/conversations/{id}/messages":{"get":{"tags":["Backend do cliente"],"summary":"Consultar mensagens de uma conversa","security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID da conversa.","schema":{"type":"string"}},{"name":"page","in":"query","description":"Página desejada (padrão: 1).","schema":{"type":"integer","minimum":1,"default":1}},{"name":"pageSize","in":"query","description":"Itens por página.","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Mensagens paginadas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedMessages"}}}}}},"post":{"tags":["Backend do cliente"],"summary":"Enviar mensagem pelo seu servidor","security":[{"secretKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID da conversa.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Conteúdo da mensagem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageInput"},"example":{"body":"Olá, como podemos ajudar?"}}}},"responses":{"201":{"description":"Mensagem criada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}}}}},"/webhooks":{"get":{"tags":["Webhooks"],"summary":"Listar webhooks da empresa","security":[{"bearerAuth":[]}],"parameters":[{"name":"projectId","in":"query","required":true,"description":"ID interno do projeto.","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhooks configurados.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}}}},"post":{"tags":["Webhooks"],"summary":"Criar webhook","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"description":"URL e eventos que devem disparar o webhook.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"},"example":{"projectId":"proj_abc123","url":"https://app.exemplo.com/webhooks/seuchat","events":["message.created","conversation.closed"]}}}},"responses":{"201":{"description":"Webhook criado. Guarde o secret: ele é exibido integralmente somente nesta resposta.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}}},"/webhooks/{id}":{"patch":{"tags":["Webhooks"],"summary":"Editar webhook","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID do webhook.","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Campos que devem ser alterados.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookUpdate"},"example":{"isActive":false}}}},"responses":{"200":{"description":"Webhook atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Webhook"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Remover webhook","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID do webhook.","schema":{"type":"string"}}],"responses":{"200":{"description":"Webhook removido.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}}}}},"/webhooks/{id}/deliveries":{"get":{"tags":["Webhooks"],"summary":"Ver entregas de um webhook","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID do webhook.","schema":{"type":"string"}}],"responses":{"200":{"description":"Últimas entregas.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}},"/webhooks/{id}/deliveries/{deliveryId}/retry":{"post":{"tags":["Webhooks"],"summary":"Reenviar uma entrega","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"ID do webhook.","schema":{"type":"string"}},{"name":"deliveryId","in":"path","required":true,"description":"ID da entrega.","schema":{"type":"string"}}],"responses":{"200":{"description":"Reenvio solicitado.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}}},"example":{"success":true}}}}}}}}}