{ "openapi": "3.0.1", "info": { "title": "API do Treble Poll", "description": "Documentação para o endpoint de implantação de polls no Treble", "version": "1.0.0" }, "servers": [ { "url": "https://main.treble.ai", "description": "Servidor principal do Treble" }, { "url": "https://seudominio.com", "description": "Servidor de exemplo para implementar os webhooks. Isso representa SEU servidor onde você deve implementar os endpoints que o Treble chamará." } ], "paths": { "/deployment/api/poll/{poll_id}": { "post": { "summary": "Implantar um poll para usuários específicos", "description": "Este endpoint permite implantar uma conversa para uma lista de usuários definidos pelo seu número de telefone e código de país. Também permite agendar implantações para uma data futura.", "parameters": [ { "name": "poll_id", "in": "path", "required": true, "description": "ID do poll que você deseja implantar", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "description": "Chave API de autorização. Pode ser obtida em https://app.treble.ai/en/dashboard/settings", "schema": { "type": "string" }, "example": "API_KEY" }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": ["application/json"] } } ], "requestBody": { "description": "Informações dos usuários para os quais o poll será implantado", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["users"], "properties": { "users": { "type": "array", "description": "Lista de usuários para os quais o poll será implantado", "items": { "type": "object", "required": [ "cellphone", "country_code", "user_session_keys" ], "properties": { "cellphone": { "type": "string", "description": "Número de telefone do usuário sem o código do país (por exemplo: '3051234567')" }, "country_code": { "type": "string", "description": "Código do país com o símbolo + (por exemplo: '+57')" }, "user_session_keys": { "type": "array", "description": "Variáveis que podem ser substituídas nos textos das perguntas ou entregues quando um webhook é chamado. Para empresas multicanal, pode incluir a chave 'deployment_squad' para selecionar qual número de telefone realizará a implantação.", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string", "description": "Nome da variável. Valores especiais incluem 'deployment_squad' para selecionar qual número de telefone realizará a implantação em empresas multicanal." }, "value": { "type": "string", "description": "Valor da variável. Para 'deployment_squad', o valor deve ser 'DS_[CELLPHONE]'." } } } }, "deployment_eta": { "type": "integer", "description": "Timestamp UNIX UTC para agendar a implantação para uma data futura (opcional). Exemplo: 1615823201 (15 de março de 2021, 3:46:41 PM UTC)" } } } } } }, "examples": { "Exemplo básico": { "value": { "users": [ { "cellphone": "3051234567", "country_code": "+57", "user_session_keys": [ { "key": "name", "value": "João" }, { "key": "TransID", "value": "12345" }, { "key": "schoolname", "value": "Redschool" } ] } ] } }, "Exemplo com deployment_eta": { "value": { "users": [ { "cellphone": "3051234567", "country_code": "+57", "user_session_keys": [ { "key": "name", "value": "João" } ], "deployment_eta": 1615823201 } ] } }, "Exemplo com deployment_squad": { "value": { "users": [ { "cellphone": "3051234567", "country_code": "+57", "user_session_keys": [ { "key": "name", "value": "João" }, { "key": "deployment_squad", "value": "DS_[CELLPHONE]" } ] } ] } } } } } }, "responses": { "200": { "description": "O poll foi implantado corretamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Mensagem de confirmação" }, "id": { "type": "string", "description": "ID da implantação" }, "batch_id": { "type": "string", "description": "ID do lote de implantação" }, "new_last_scheduleded_deployment": { "type": "string", "format": "date-time", "description": "Data e hora da última implantação programada" }, "conversations_id": { "type": "array", "items": { "type": "string" }, "description": "Lista de IDs das conversas criadas" } } }, "example": { "message": "The poll was deployed", "id": "5f8d7e6a5f8d7e6a5f8d7e6a", "batch_id": "5f8d7e6a5f8d7e6a5f8d7e6b", "new_last_scheduleded_deployment": "2021-03-15T15:46:41Z", "conversations_id": ["5f8d7e6a5f8d7e6a5f8d7e6c"] } } } }, "400": { "description": "Erro na solicitação", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } }, "401": { "description": "Não autorizado. Chave API inválida ou ausente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } }, "404": { "description": "Poll não encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } } } } }, "/poll/api/all": { "get": { "summary": "Obter todas as conversas (fluxos) da sua empresa", "description": "Este endpoint permite obter todas as conversas (fluxos) que pertencem à sua empresa.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Chave API de autorização. Pode ser obtida em https://app.treble.ai/en/dashboard/settings", "schema": { "type": "string" }, "example": "API_KEY" } ], "responses": { "200": { "description": "Lista de conversas obtida corretamente", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "example": [ { "id": 1, "name": "Primeira conversa" }, { "id": 2, "name": "Integração CRM" } ] } } }, "401": { "description": "Não autorizado. Chave API inválida ou ausente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } }, "500": { "description": "Erro interno do servidor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } } } } }, "/treble-webhooks": { "post": { "summary": "Webhook - Eventos do Treble", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/treble-webhooks). O Treble chamará este webhook para diferentes tipos de eventos. Você deve configurar a URL deste webhook no painel de administração do Treble.", "tags": ["Webhooks"], "servers": [ { "url": "https://{webhookUrl}", "description": "Enter your webhook endpoint URL", "variables": { "webhookUrl": { "default": "seudominio.com", "description": "URL do seu servidor onde o webhook será implementado" } } } ], "requestBody": { "description": "Informações do evento. O tipo de evento é determinado pelo campo 'event_type'.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/HSMStatusUpdateEvent" }, { "$ref": "#/components/schemas/ConversationClosedEvent" }, { "$ref": "#/components/schemas/DeploymentFailureEvent" } ], "discriminator": { "propertyName": "event_type", "mapping": { "hsm.status": "#/components/schemas/HSMStatusUpdateEvent", "session.close": "#/components/schemas/ConversationClosedEvent", "deployment.failure": "#/components/schemas/DeploymentFailureEvent" } } }, "examples": { "hsm.status": { "summary": "Atualização de status HSM", "value": { "event_type": "hsm.status", "event_id": "5f8d7e6a5f8d7e6a5f8d7e6a", "timestamp": "2024-09-10T12:34:56.789Z", "status": "APPROVED", "name": "welcome_message", "affected_conversation_ids": [12345, 67890, 54321] } }, "session.close": { "summary": "Conversa fechada", "value": { "event_type": "session.close", "event_id": "f49e36d5-e0b0-4831-87c3-21c4bff033b2", "timestamp": "2024-09-10T14:50:40.145000Z", "session": { "external_id": "f49e36d5-e0b0-4831-87c3-21c4bff033b2", "closed_at": "2024-09-10T14:50:40.145000Z" }, "user": { "country_code": "+57", "cellphone": "1234567890" }, "company": { "id": 1, "cellphone": "+12056192992" }, "messages": [ { "sender": "user", "type": "text", "text": { "message": "Hello, how are you?" }, "created_at": "2024-09-10T14:50:30.145000Z", "delivered_at": null, "read_at": null }, { "sender": "company", "type": "text", "text": { "message": "Hello, how are you?, what's your name?" }, "created_at": "2024-09-10T14:50:30.145000Z", "delivered_at": "2024-09-10T14:50:31.145000Z", "read_at": "2024-09-10T14:50:32.145000Z" } ], "user_session_keys": [ { "key": "name", "value": "John", "type": null }, { "key": "location", "value": "{\"latitude\": 4.5935443, \"longitude\": -72.0345404, \"address\": \"Carrera 7 #100-06\"}", "type": "location" } ], "hsm": { "name": "welcome_message", "text": "Olá {{1}}, bem-vindo ao nosso serviço de atendimento ao cliente.", "answers": [ { "message": "Obrigado pela boas-vindas" } ], "header": { "type": "image", "url": "https://example.com/logo.jpg" }, "footer": "Responda a esta mensagem para continuar", "buttons": { "type": "actions", "options": [ { "type": "quick_reply", "message": "Preciso de ajuda" }, { "type": "call_to_action", "subtype": "website", "url": "https://example.com/catalog", "message": "Ver catálogo" } ] } } } }, "deployment.failure": { "summary": "Falha na implantação", "value": { "event_id": "f49e36d5-e0b0-4831-87c3-21c4bff033b2", "timestamp": "2024-09-10T14:50:44.145000Z", "event_type": "deployment.failure", "failure_reason": "FAILURE_BY_HUMAN_HANDOVER", "user": { "country_code": "+57", "cellphone": "3178901234" }, "conversation_id": 1, "failed_at": "2024-09-10T14:50:44.145000Z", "user_session_keys": [ { "key": "name", "value": "John", "type": null } ] } } } } } }, "responses": { "200": { "description": "Resposta bem-sucedida", "content": { "application/json": { "schema": { "type": "object", "description": "Objeto JSON com a confirmação de recepção. O serviço deve responder em menos de 5 segundos." } } } } } } }, "/devapi/poll/{poll_id}/sessions": { "get": { "summary": "Obter metadados de sessões de um poll", "description": "Este endpoint, dado um ID de poll, retorna os metadados de todas as sessões de forma paginada. Por padrão, traz os primeiros 1000 registros do ano atual. Parâmetros opcionais podem ser usados para controlar o intervalo de datas e a paginação.", "parameters": [ { "name": "poll_id", "in": "path", "required": true, "description": "ID do poll do qual você deseja obter as sessões", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "description": "Chave API de autorização. Pode ser obtida em https://app.treble.ai/en/dashboard/settings", "schema": { "type": "string" }, "example": "API_KEY" }, { "name": "since", "in": "query", "required": false, "description": "Timestamp UNIX UTC para a data de início do intervalo a consultar", "schema": { "type": "integer" } }, { "name": "until", "in": "query", "required": false, "description": "Timestamp UNIX UTC para a data final do intervalo a consultar", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Número inteiro entre 1 e 10.000 que indica a quantidade de sessões a recuperar", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, { "name": "after", "in": "query", "required": false, "description": "Cursor de paginação retornado na propriedade 'next_id' da resposta anterior", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Lista de metadados de sessões obtida corretamente", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único da sessão" }, "created_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a sessão foi criada" }, "finished_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a sessão foi finalizada" }, "user": { "type": "object", "properties": { "country_code": { "type": "string", "description": "Código do país do usuário" }, "cellphone": { "type": "string", "description": "Número de telefone do usuário sem o código do país" } } } } }, "description": "Lista de metadados de sessões" }, "next_id": { "type": "string", "description": "Cursor para obter a próxima página de resultados" } } }, "example": { "results": [ { "id": "dabcf6c0-8150-4231-bafd-a3c331da385f4", "created_at": "2022-03-09 17:00:28.956422", "finished_at": "2022-03-09 19:08:38.808986", "user": { "country_code": "+57", "cellphone": "987654321" } }, { "id": "dabcf6c0-8850-4231-bafd-a3c331da385f9", "created_at": "2022-03-09 17:11:46.754945", "finished_at": "2022-03-09 19:18:41.401605", "user": { "country_code": "+57", "cellphone": "123456789" } } ], "next_id": "da848b5f-27e2-49f9-8d31-313b791daf8d" } } } }, "401": { "description": "Não autorizado. Chave API inválida ou ausente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } }, "404": { "description": "Poll não encontrado", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } } } } }, "/devapi/session/{session_id}/history": { "get": { "summary": "Obter histórico de mensagens de uma sessão", "description": "Este endpoint, dado um ID de sessão, retorna o histórico completo de mensagens para essa sessão específica.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "ID da sessão da qual você deseja obter o histórico de mensagens", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "description": "Chave API de autorização. Pode ser obtida em https://app.treble.ai/en/dashboard/settings", "schema": { "type": "string" }, "example": "API_KEY" } ], "responses": { "200": { "description": "Histórico de mensagens obtido corretamente", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo de entrada no histórico", "example": "MESSAGE" }, "message": { "type": "object", "properties": { "type": { "type": "string", "description": "Tipo de mensagem", "example": "TEXT" }, "sender": { "type": "string", "description": "Remetente da mensagem", "example": "USER" }, "text": { "type": "string", "description": "Conteúdo da mensagem" }, "file_url": { "type": "string", "nullable": true, "description": "URL do arquivo anexado (se existir)" }, "created_at": { "type": "integer", "description": "Timestamp UNIX UTC de criação da mensagem" }, "delivered_at": { "type": "integer", "nullable": true, "description": "Timestamp UNIX UTC de entrega da mensagem" }, "read_at": { "type": "integer", "nullable": true, "description": "Timestamp UNIX UTC de leitura da mensagem" }, "extra": { "type": "object", "nullable": true, "description": "Informações adicionais da mensagem" } } } } } }, "example": [ { "type": "MESSAGE", "message": { "type": "TEXT", "sender": "USER", "text": "Hi", "file_url": null, "created_at": 1653341789, "delivered_at": null, "read_at": null, "extra": null } }, { "type": "MESSAGE", "message": { "type": "TEXT", "sender": "AI", "text": "I need help", "file_url": null, "created_at": 1653341803, "delivered_at": 1653341804, "read_at": 1653342120, "extra": null } } ] } } }, "401": { "description": "Não autorizado. Chave API inválida ou ausente.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } }, "404": { "description": "Sessão não encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } } } } }, "/session/{session_external_id}/update": { "post": { "summary": "Atualizar sessão do usuário e continuar conversa", "description": "Este endpoint permite atualizar as chaves de sessão de um usuário específico e continuar a conversa iniciada anteriormente. O webhook desencadeado pela primeira resposta do usuário fornecerá o session_external_id necessário para esta solicitação.", "parameters": [ { "name": "session_external_id", "in": "path", "required": true, "description": "ID externo da sessão do usuário. Obtido do campo 'session_external_id' na resposta do webhook desencadeado pela primeira interação do usuário.", "schema": { "type": "string" }, "example": "f33b4734a2e5db671b59877ed3f662ec1f6332a0418c25de4868e35a" }, { "name": "content-type", "in": "header", "required": true, "schema": { "type": "string", "enum": ["application/json"] } } ], "requestBody": { "description": "Informações das chaves de sessão a serem atualizadas", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["user_session_keys"], "properties": { "user_session_keys": { "type": "array", "description": "Lista de chaves de sessão do usuário a serem atualizadas", "items": { "$ref": "#/components/schemas/UserSessionKey" } } } }, "example": { "user_session_keys": [ { "key": "order", "value": "1 Hambúrguer com queijo, 2 Refrigerantes" } ] } } } }, "responses": { "200": { "description": "Sessão atualizada com sucesso", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Mensagem de confirmação" }, "session_id": { "type": "string", "description": "ID da sessão atualizada" } } }, "example": { "message": "Sessão atualizada com sucesso", "session_id": "f33b4734a2e5db671b59877ed3f662ec1f6332a0418c25de4868e35a" } } } }, "400": { "description": "Erro na solicitação", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } }, "404": { "description": "Sessão não encontrada", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Código de erro" }, "message": { "type": "string", "description": "Descrição do erro" } } } } } } } } }, "/webhooks/on-delivered": { "post": { "summary": "Webhook - Quando uma mensagem é entregue", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/webhooks/on-delivered). O Treble chamará este webhook quando uma mensagem for entregue ao usuário. Você deve configurar a URL deste webhook no painel de administração do Treble.", "tags": ["Webhooks"], "servers": [ { "url": "https://seudominio.com", "description": "Seu servidor onde você deve implementar este webhook" } ], "requestBody": { "description": "Informações do evento de entrega", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveredEvent" }, "example": { "country_code": "+57", "cellphone": "3176477608", "session_id": "d2fa98d29a2670dfa119335df1b0371720d674f1677302aba228876a", "conversation_id": 34820, "question": { "type": "open", "text": "Olá! Bom dia. Espero que esteja tudo bem. Gostaria de continuar nossa conversa para resolver todos os seus problemas e preocupações?" }, "sent_at": "2021-06-22 15:19:06.473256", "sent_text": "Olá! Bom dia. Espero que esteja tudo bem. Gostaria de continuar nossa conversa para resolver todos os seus problemas e preocupações?", "user_session_keys": [], "delivered_at": "2021-06-22 15:19:08" } } } }, "responses": { "200": { "description": "Resposta para atualizar ou adicionar informações à sessão", "content": { "application/json": { "schema": { "type": "object", "description": "Objeto JSON com as novas informações que serão substituídas ou adicionadas à sessão para uso futuro. O serviço deve responder em menos de 10 segundos." } } } } } } }, "/webhooks/on-read": { "post": { "summary": "Webhook - Quando uma mensagem é lida", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/webhooks/on-read). O Treble chamará este webhook quando uma mensagem for lida pelo usuário. Você deve configurar a URL deste webhook no painel de administração do Treble.", "tags": ["Webhooks"], "servers": [ { "url": "https://seudominio.com", "description": "Seu servidor onde você deve implementar este webhook" } ], "requestBody": { "description": "Informações do evento de leitura", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadEvent" }, "example": { "country_code": "+57", "cellphone": "3176477608", "session_id": "d2fa98d29a2670dfa119335df1b0371720d674f1677302aba228876a", "conversation_id": 34820, "question": { "type": "open", "text": "Olá! Bom dia. Espero que esteja tudo bem. Gostaria de continuar nossa conversa para resolver todos os seus problemas e preocupações?" }, "sent_at": "2021-06-22 15:19:06.473256", "sent_text": "Olá! Bom dia. Espero que esteja tudo bem. Gostaria de continuar nossa conversa para resolver todos os seus problemas e preocupações?", "user_session_keys": [], "read_at": "2021-06-22 15:19:08" } } } }, "responses": { "200": { "description": "Resposta para atualizar ou adicionar informações à sessão", "content": { "application/json": { "schema": { "type": "object", "description": "Objeto JSON com as novas informações que serão substituídas ou adicionadas à sessão para uso futuro. O serviço deve responder em menos de 10 segundos." } } } } } } }, "/webhooks/on-response": { "post": { "summary": "Webhook - Quando um usuário responde a uma pergunta", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/webhooks/on-response). O Treble chamará este webhook quando um usuário responder a uma pergunta na conversa. Você deve configurar a URL deste webhook no painel de administração do Treble.", "tags": ["Webhooks"], "servers": [ { "url": "https://seudominio.com", "description": "Seu servidor onde você deve implementar este webhook" } ], "requestBody": { "description": "Informações do evento de resposta", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseEvent" }, "example": { "country_code": "+57", "cellphone": "3161234567", "session_id": "1234", "conversation_id": "5678", "question": { "type": "closed", "text": "texto-da-pergunta-da-conversa", "answers": [{ "text": "texto-da-resposta" }] }, "sent_at": "2019-01-01 00:00:00", "responded_at": "2019-01-01 00:00:00", "sent_text": "texto-enviado-ao-usuário", "actual_response": "Sim, preciso", "classified_answer": { "text": "texto-da-resposta" }, "user_session_keys": [ { "key": "name", "value": "João", "type": null }, { "key": "user_id", "value": "12345", "type": null }, { "key": "loc", "value": "{\"latitude\": 4.5935443, \"longitude\": -72.0345404, \"address\": \"Carrera 7 #100-06\"}", "type": "location" } ] } } } }, "responses": { "200": { "description": "Resposta para atualizar ou adicionar informações à sessão", "content": { "application/json": { "schema": { "type": "object", "description": "Objeto JSON com as novas informações que serão substituídas ou adicionadas à sessão para uso futuro. O serviço deve responder em menos de 10 segundos." } } } } } } }, "/webhooks/on-optout": { "post": { "summary": "Webhook - Quando um usuário cancela a inscrição (opt-out)", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/webhooks/on-optout). O Treble chamará este webhook quando um usuário decidir cancelar a inscrição ou sair da conversa. Você deve configurar a URL deste webhook no painel de administração do Treble.", "tags": ["Webhooks"], "servers": [ { "url": "https://seudominio.com", "description": "Seu servidor onde você deve implementar este webhook" } ], "requestBody": { "description": "Informações do evento de cancelamento de inscrição", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOutEvent" }, "example": { "country_code": "+57", "cellphone": "3176477608", "session_id": "85b398ef5bcb20c355f3710c4509349784c907673c9118fb7a89c7a8", "conversation_id": 54263, "question": { "type": "closed", "text": "Oi! Obrigado por participar do nosso webinar hoje. Gostaríamos de ter um feedback sobre nossa sessão e ficaríamos muito gratos se você pudesse nos ajudar com isso. ", "answers": [ {"text": "Claro"}, {"text": "Não, obrigado"}, {"text": "PADRÃO"} ] }, "sent_at": "2021-10-22 00:15:39.044704", "sent_text": "Oi! Obrigado por participar do nosso webinar hoje. Gostaríamos de ter um feedback sobre nossa sessão e ficaríamos muito gratos se você pudesse nos ajudar com isso. \n1) Claro\n2) Não, obrigado\n3) PADRÃO", "user_session_keys": [], "classified_answer": { "text": "Não, obrigado" }, "reason": "OPTOUT" } } } }, "responses": { "200": { "description": "Resposta para atualizar ou adicionar informações à sessão", "content": { "application/json": { "schema": { "type": "object", "description": "Objeto JSON com as novas informações que serão substituídas ou adicionadas à sessão para uso futuro. O serviço deve responder em menos de 10 segundos." } } } } } } }, "/webhooks/on-condition": { "post": { "summary": "Webhook - Quando um nó condicional é avaliado", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/webhooks/on-condition). O Treble chamará este webhook quando um nó condicional for avaliado na conversa. Você deve configurar a URL deste webhook no painel de administração do Treble.", "tags": ["Webhooks"], "servers": [ { "url": "https://seudominio.com", "description": "Seu servidor onde você deve implementar este webhook" } ], "requestBody": { "description": "Informações do evento de avaliação de condição", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConditionEvent" }, "example": { "country_code": "+57", "cellphone": "3161234567", "session_id": "abcsderfwer3252432423-1324325235", "conversation_id": 1234, "variable": { "name": "age", "value": "18" }, "condition": { "operator": "EQ", "value": "18" }, "user_session_keys": [ { "key": "age", "value": "18", "type": null }, { "key": "user_id", "value": "12345", "type": null } ] } } } }, "responses": { "200": { "description": "Resposta para atualizar ou adicionar informações à sessão", "content": { "application/json": { "schema": { "type": "object", "description": "Objeto JSON com as novas informações que serão substituídas ou adicionadas à sessão para uso futuro. O serviço deve responder em menos de 10 segundos." } } } } } } }, "/webhooks/on-timeout": { "post": { "summary": "Webhook - Quando ocorre um timeout na conversa", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/webhooks/on-timeout). O Treble chamará este webhook quando ocorrer um timeout na conversa (o usuário não responde dentro do tempo estabelecido). Você deve configurar a URL deste webhook no painel de administração do Treble.", "tags": ["Webhooks"], "servers": [ { "url": "https://seudominio.com", "description": "Seu servidor onde você deve implementar este webhook" } ], "requestBody": { "description": "Informações do evento de timeout", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoutEvent" }, "example": { "country_code": "+57", "cellphone": "3161234567", "session_id": "abcsderfwer3252432423-1324325235", "conversation_id": 1234, "question": { "type": "open", "text": "Olá mundo" }, "timeout_at": "2021-10-07 08:53:22.572123", "user_session_keys": [ { "key": "age", "value": "18", "type": null }, { "key": "user_id", "value": "12345", "type": null } ] } } } }, "responses": { "200": { "description": "Resposta para atualizar ou adicionar informações à sessão", "content": { "application/json": { "schema": { "type": "object", "description": "Objeto JSON com as novas informações que serão substituídas ou adicionadas à sessão para uso futuro. O serviço deve responder em menos de 10 segundos." } } } } } } }, "/agent/company/agents": { "get": { "summary": "Obter os agentes da sua empresa", "description": "Devolve os agentes da sua conta que podem receber conversas. Use-o para conhecer o `id` e o `email` de cada agente, que são os valores que você deve devolver do seu endpoint quando usa o destino **API** do bloco de Métodos de transferência.\n\nApenas os agentes **ativos** são devolvidos, portanto qualquer agente da resposta pode receber uma conversa.\n\nEste endpoint vive no host da plataforma de agentes, `agent-api.treble.ai`, e não em `main.treble.ai`.", "servers": [ { "url": "https://agent-api.treble.ai", "description": "Host da plataforma de agentes do Treble" } ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "API Key de autorização. Pode ser obtida em https://app.treble.ai/pt/dashboard/settings/developers", "schema": { "type": "string" }, "example": "API_KEY" } ], "responses": { "200": { "description": "Lista de agentes obtida corretamente", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "example": [ { "id": 4567, "first_name": "Andrea", "last_name": "Soto", "email": "andrea.soto@suaempresa.com", "tags": [ { "id": 12, "name": "Default" }, { "id": 18, "name": "Comercial" } ] } ] } } } } } }, "/webhooks/on-agent-assignation": { "post": { "summary": "Webhook - Decidir qual agente recebe a conversa", "description": "Este endpoint deve ser implementado no SEU servidor (por exemplo: https://seudominio.com/webhooks/on-agent-assignation). O Treble o chamará quando uma conversa chegar a um bloco de **Métodos de transferência** configurado com o destino **API**, para que o seu sistema decida qual agente deve receber o chat.\n\nA URL é configurada no próprio bloco, dentro do editor de conversas. Se você ativar a autenticação por Token / API Key, o Treble incluirá o seu token no header `Authorization` com o formato `Bearer SEU_TOKEN`.\n\nVocê deve responder em menos de 10 segundos. Se o seu servidor não responder a tempo, devolver um código diferente de 200, ou devolver um agente que não pode receber a conversa, o Treble aplicará o método de reserva configurado na plataforma principal.", "tags": [ "Webhooks" ], "servers": [ { "url": "https://seudominio.com", "description": "Seu servidor onde você deve implementar este webhook" } ], "parameters": [ { "name": "Authorization", "in": "header", "required": false, "description": "Apenas se você configurou autenticação por Token / API Key no bloco. O Treble envia o token com o formato `Bearer SEU_TOKEN`.", "schema": { "type": "string" }, "example": "Bearer SEU_TOKEN" } ], "requestBody": { "description": "Contexto do contato e da conversa que o Treble envia ao seu endpoint", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAssignationRequest" }, "example": { "company_id": 1234, "survey_user_id": 567890, "contact": { "treble_id": "5215512345678", "name": "Andrea Soto", "country_code": "52", "cellphone": "5512345678", "business_scope_id": "1029384756", "username": null }, "crm_type": "salesforce", "crm_objects": [ { "entity": "Contact", "id": "0035f00000ABCDEqAO" }, { "entity": "Account", "id": "0015f00000FGHIJqAO" } ], "channel": { "phone_number_id": "1234567890" }, "metadata": { "poll_id": 4321, "node_id": "a1b2c3", "tag": "Comercial", "language": "es" } } } } }, "responses": { "200": { "description": "Agente ao qual o Treble deve atribuir a conversa. Devolva `agent_id` (recomendado) ou `agent_email`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAssignationResponse" }, "example": { "agent_id": 4567 } } } } } } } }, "components": { "schemas": { "UserSessionKey": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string", "description": "Nome da variável. Valores especiais incluem 'deployment_squad' para selecionar qual número de telefone realizará a implantação em empresas multicanal." }, "value": { "type": "string", "description": "Valor da variável. Para 'deployment_squad', o valor deve ser 'DS_[CELLPHONE]'." } } }, "User": { "type": "object", "required": ["cellphone", "country_code", "user_session_keys"], "properties": { "cellphone": { "type": "string", "description": "Número de telefone do usuário sem o código do país (por exemplo: '3051234567')" }, "country_code": { "type": "string", "description": "Código do país com o símbolo + (por exemplo: '+57')" }, "user_session_keys": { "type": "array", "description": "Variáveis que podem ser substituídas nos textos das perguntas ou entregues quando um webhook é chamado. Para empresas multicanal, pode incluir a chave 'deployment_squad' para selecionar qual número de telefone realizará a implantação.", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "deployment_eta": { "type": "integer", "description": "Timestamp UNIX UTC para agendar a implantação para uma data futura (opcional). Exemplo: 1615823201 (15 de março de 2021, 3:46:41 PM UTC)" } } }, "DeploymentSquadKey": { "type": "object", "description": "Chave especial para empresas multicanal que permite selecionar qual número de telefone realizará a implantação.", "required": ["key", "value"], "properties": { "key": { "type": "string", "enum": ["deployment_squad"], "description": "Chave para especificar um número de telefone que realizará a implantação." }, "value": { "type": "string", "pattern": "^DS_\\[CELLPHONE\\]$", "description": "Valor que deve seguir o formato 'DS_[CELLPHONE]'. Podem ser adicionados vários deployment squads para que vários números possam realizar a implantação." } } }, "Conversation": { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "integer", "description": "ID único da conversa" }, "name": { "type": "string", "description": "Nome da conversa" } } }, "Question": { "type": "object", "required": ["type", "text"], "properties": { "type": { "type": "string", "description": "Tipo de pergunta", "example": "open" }, "text": { "type": "string", "description": "Texto da pergunta" } } }, "ClosedQuestion": { "type": "object", "required": ["type", "text", "answers"], "properties": { "type": { "type": "string", "description": "Tipo de pergunta", "example": "closed" }, "text": { "type": "string", "description": "Texto da pergunta" }, "answers": { "type": "array", "description": "Lista de respostas possíveis para a pergunta fechada", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Texto da resposta" } } } } } }, "Answer": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string", "description": "Texto da resposta" } } }, "ExtendedUserSessionKey": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string", "description": "Nome da variável" }, "value": { "type": "string", "description": "Valor da variável" }, "type": { "type": "string", "nullable": true, "description": "Tipo da variável. Pode ser null ou um tipo específico como 'location'." } } }, "DeliveredEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "sent_at", "sent_text", "delivered_at" ], "description": "Evento que é disparado quando uma mensagem é entregue ao usuário", "properties": { "country_code": { "type": "string", "description": "Código do país do usuário" }, "cellphone": { "type": "string", "description": "Número de telefone do usuário sem o código do país" }, "session_id": { "type": "string", "description": "ID da sessão do usuário" }, "conversation_id": { "type": "integer", "description": "ID da conversa" }, "question": { "$ref": "#/components/schemas/Question" }, "sent_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a mensagem foi enviada" }, "sent_text": { "type": "string", "description": "Texto da mensagem enviada" }, "user_session_keys": { "type": "array", "description": "Chaves de sessão do usuário coletadas durante a conversa ou fornecidas durante a implantação", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "delivered_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a mensagem foi entregue ao usuário" } } }, "ReadEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "sent_at", "sent_text", "read_at" ], "description": "Evento que é disparado quando uma mensagem é lida pelo usuário", "properties": { "country_code": { "type": "string", "description": "Código do país do usuário" }, "cellphone": { "type": "string", "description": "Número de telefone do usuário sem o código do país" }, "session_id": { "type": "string", "description": "ID da sessão do usuário" }, "conversation_id": { "type": "integer", "description": "ID da conversa" }, "question": { "$ref": "#/components/schemas/Question" }, "sent_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a mensagem foi enviada" }, "sent_text": { "type": "string", "description": "Texto da mensagem enviada" }, "user_session_keys": { "type": "array", "description": "Chaves de sessão do usuário coletadas durante a conversa ou fornecidas durante a implantação", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "read_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a mensagem foi lida pelo usuário" } } }, "ResponseEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "sent_at", "responded_at", "sent_text", "actual_response", "classified_answer", "user_session_keys" ], "description": "Evento que é disparado quando um usuário responde a uma pergunta na conversa", "properties": { "country_code": { "type": "string", "description": "Código do país do usuário" }, "cellphone": { "type": "string", "description": "Número de telefone do usuário sem o código do país" }, "session_id": { "type": "string", "description": "ID da sessão do usuário" }, "conversation_id": { "type": "string", "description": "ID da conversa" }, "question": { "$ref": "#/components/schemas/ClosedQuestion" }, "sent_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a pergunta foi enviada" }, "responded_at": { "type": "string", "format": "date-time", "description": "Data e hora em que o usuário respondeu à pergunta" }, "sent_text": { "type": "string", "description": "Texto enviado ao usuário" }, "actual_response": { "type": "string", "description": "Resposta literal fornecida pelo usuário" }, "classified_answer": { "$ref": "#/components/schemas/Answer", "description": "Resposta classificada baseada na resposta do usuário" }, "user_session_keys": { "type": "array", "description": "Claves de sesión del usuario recopiladas durante la conversación o proporcionadas durante el despliegue", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } } } }, "OptOutEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "sent_at", "sent_text", "classified_answer", "reason" ], "description": "Evento que é disparado quando um usuário decide cancelar a inscrição ou sair da conversa", "properties": { "country_code": { "type": "string", "description": "Código de país del usuario" }, "cellphone": { "type": "string", "description": "Número de teléfono del usuario sin el código de país" }, "session_id": { "type": "string", "description": "ID de la sesión del usuario" }, "conversation_id": { "type": "integer", "description": "ID de la conversación" }, "question": { "$ref": "#/components/schemas/ClosedQuestion" }, "sent_at": { "type": "string", "format": "date-time", "description": "Fecha y hora en que se envió la pregunta" }, "sent_text": { "type": "string", "description": "Texto enviado ao usuário" }, "user_session_keys": { "type": "array", "description": "Claves de sesión del usuario recopiladas durante la conversación o proporcionadas durante el despliegue", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "classified_answer": { "$ref": "#/components/schemas/Answer", "description": "Resposta classificada baseada na resposta do usuário" }, "reason": { "type": "string", "description": "Razão da saída do usuário, neste caso 'OPTOUT' para indicar que o usuário decidiu cancelar a inscrição", "enum": ["OPTOUT"] } } }, "Variable": { "type": "object", "required": ["name", "value"], "properties": { "name": { "type": "string", "description": "Nome da variável que é avaliada na condição" }, "value": { "type": "string", "description": "Valor actual de la variable" } } }, "Condition": { "type": "object", "required": ["operator", "value"], "properties": { "operator": { "type": "string", "description": "Operador utilizado para avaliar a condição (por exemplo: 'EQ' para igual, 'GT' para maior que, etc.)", "enum": ["EQ", "GT", "LT", "GTE", "LTE", "NEQ"] }, "value": { "type": "string", "description": "Valor contra o qual a variável é comparada" } } }, "ConditionEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "variable", "condition", "user_session_keys" ], "description": "Evento que é disparado quando um nó condicional é avaliado na conversa", "properties": { "country_code": { "type": "string", "description": "Código de país del usuario" }, "cellphone": { "type": "string", "description": "Número de teléfono del usuario sin el código de país" }, "session_id": { "type": "string", "description": "ID de la sesión del usuario" }, "conversation_id": { "type": "integer", "description": "ID de la conversación" }, "variable": { "$ref": "#/components/schemas/Variable", "description": "Variável que é avaliada na condição" }, "condition": { "$ref": "#/components/schemas/Condition", "description": "Condição que é avaliada" }, "user_session_keys": { "type": "array", "description": "Claves de sesión del usuario recopiladas durante la conversación o proporcionadas durante el despliegue", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } } } }, "TimeoutEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "timeout_at", "user_session_keys" ], "description": "Evento que é disparado quando ocorre um timeout na conversa (o usuário não responde dentro do tempo estabelecido)", "properties": { "country_code": { "type": "string", "description": "Código de país del usuario" }, "cellphone": { "type": "string", "description": "Número de teléfono del usuario sin el código de país" }, "session_id": { "type": "string", "description": "ID de la sesión del usuario" }, "conversation_id": { "type": "integer", "description": "ID de la conversación" }, "question": { "$ref": "#/components/schemas/Question", "description": "Pergunta que não recebeu resposta a tempo" }, "timeout_at": { "type": "string", "format": "date-time", "description": "Data e hora em que ocorreu o timeout" }, "user_session_keys": { "type": "array", "description": "Claves de sesión del usuario recopiladas durante la conversación o proporcionadas durante el despliegue", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } } } }, "Session": { "type": "object", "required": ["external_id", "closed_at"], "properties": { "external_id": { "type": "string", "description": "ID externo único da sessão" }, "closed_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a conversa foi fechada" } } }, "UserInfo": { "type": "object", "required": ["country_code", "cellphone"], "properties": { "country_code": { "type": "string", "description": "Código de país del usuario" }, "cellphone": { "type": "string", "description": "Número de teléfono del usuario sin el código de país" } } }, "CompanyInfo": { "type": "object", "required": ["id", "cellphone"], "properties": { "id": { "type": "integer", "description": "ID da empresa no Treble" }, "cellphone": { "type": "string", "description": "Número de telefone da empresa" } } }, "TextMessage": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "Conteúdo da mensagem de texto" } } }, "HSMMessage": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "Conteúdo da mensagem HSM" } } }, "MediaContent": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "description": "URL do arquivo multimídia" }, "message": { "type": "string", "description": "Legenda ou descrição do conteúdo multimídia" } } }, "LocationContent": { "type": "object", "required": ["latitude", "longitude"], "properties": { "latitude": { "type": "number", "format": "float", "description": "Latitude da localização" }, "longitude": { "type": "number", "format": "float", "description": "Longitude da localização" } } }, "Message": { "type": "object", "required": ["sender", "type", "created_at", "delivered_at", "read_at"], "properties": { "sender": { "type": "string", "description": "Quem enviou a mensagem (usuário ou empresa)", "enum": ["user", "company"] }, "type": { "type": "string", "description": "Tipo de mensagem", "enum": [ "text", "hsm", "image", "video", "audio", "document", "location" ] }, "text": { "$ref": "#/components/schemas/TextMessage" }, "hsm": { "$ref": "#/components/schemas/HSMMessage" }, "image": { "$ref": "#/components/schemas/MediaContent" }, "video": { "$ref": "#/components/schemas/MediaContent" }, "audio": { "$ref": "#/components/schemas/MediaContent" }, "document": { "$ref": "#/components/schemas/MediaContent" }, "location": { "$ref": "#/components/schemas/LocationContent" }, "created_at": { "type": "string", "format": "date-time", "description": "Data e hora em que a mensagem foi criada" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora em que a mensagem foi entregue" }, "read_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Data e hora em que a mensagem foi lida" } } }, "HSMHeaderText": { "type": "object", "required": ["type", "message"], "properties": { "type": { "type": "string", "enum": ["text"], "description": "Tipo de cabeçalho" }, "message": { "type": "string", "description": "Texto do cabeçalho" } } }, "HSMHeaderMedia": { "type": "object", "required": ["type", "url"], "properties": { "type": { "type": "string", "enum": ["image", "video", "document"], "description": "Tipo de mídia do cabeçalho" }, "url": { "type": "string", "description": "URL do arquivo multimídia do cabeçalho" } } }, "HSMButtonQuickReply": { "type": "object", "required": ["type", "message"], "properties": { "type": { "type": "string", "enum": ["quick_reply"], "description": "Tipo de botão de resposta rápida" }, "message": { "type": "string", "description": "Texto do botão de resposta rápida" } } }, "HSMButtonOTP": { "type": "object", "required": ["type", "message"], "properties": { "type": { "type": "string", "enum": ["otp"], "description": "Tipo de botão de OTP" }, "message": { "type": "string", "description": "Texto do botão de OTP" } } }, "HSMButtonCallToAction": { "type": "object", "required": ["type", "message", "subtype"], "properties": { "type": { "type": "string", "enum": ["call_to_action"], "description": "Tipo de botão de chamada para ação" }, "subtype": { "type": "string", "enum": ["website", "phone"], "description": "Subtipo de botão de chamada para ação" }, "url": { "type": "string", "description": "URL do botão de chamada para ação se o subtype for website" }, "phone": { "type": "string", "description": "Número de telefone do botão de chamada para ação se o subtype for phone" } } }, "HSMInfo": { "type": "object", "required": ["name", "text", "answers", "header", "footer", "buttons"], "properties": { "name": { "type": "string", "description": "Nome ou identificador do HSM" }, "text": { "type": "string", "description": "Texto principal do HSM" }, "answers": { "type": "array", "description": "Respostas possíveis para o HSM", "items": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "Texto da resposta" } } } }, "header": { "oneOf": [ { "$ref": "#/components/schemas/HSMHeaderText" }, { "$ref": "#/components/schemas/HSMHeaderMedia" } ], "nullable": true, "description": "Cabeçalho do HSM (pode ser texto ou multimídia)" }, "footer": { "type": "string", "nullable": true, "description": "Rodapé do HSM" }, "buttons": { "type": "object", "required": ["type", "options"], "properties": { "type": { "type": "string", "enum": ["actions", "otp"], "description": "Categoria de botões" }, "options": { "type": "array", "description": "Opções de botões", "items": { "oneOf": [ { "$ref": "#/components/schemas/HSMButtonQuickReply" }, { "$ref": "#/components/schemas/HSMButtonCallToAction" }, { "$ref": "#/components/schemas/HSMButtonOTP" } ] } } }, "nullable": true, "description": "Botões do HSM" } } }, "ConversationClosedEvent": { "title": "session.close", "type": "object", "required": [ "event_type", "event_id", "timestamp", "session", "user", "company", "messages", "user_session_keys", "hsm" ], "description": "Evento que é disparado quando uma conversa é fechada entre um usuário e a empresa", "properties": { "event_type": { "type": "string", "enum": ["session.close"], "description": "Tipo de evento, sempre 'session.close' para conversas fechadas" }, "event_id": { "type": "string", "description": "Identificador único del evento" }, "timestamp": { "type": "string", "format": "date-time", "description": "Marca de tiempo del evento en formato ISO 8601" }, "session": { "$ref": "#/components/schemas/Session", "description": "Informação da sessão fechada" }, "user": { "$ref": "#/components/schemas/UserInfo", "description": "Informação do usuário" }, "company": { "$ref": "#/components/schemas/CompanyInfo", "description": "Informação da empresa" }, "messages": { "type": "array", "description": "Mensagens trocadas durante a conversa", "items": { "$ref": "#/components/schemas/Message" } }, "user_session_keys": { "type": "array", "description": "Claves de sesión del usuario recopiladas durante la conversación", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } }, "hsm": { "$ref": "#/components/schemas/HSMInfo", "nullable": true, "description": "Informação do HSM que iniciou a conversa (se aplicável)" } } }, "HSMStatusUpdateEvent": { "title": "hsm.status", "type": "object", "required": [ "event_type", "event_id", "timestamp", "status", "name", "affected_conversation_ids" ], "description": "Evento que é disparado quando o estado de um HSM (Highly Structured Message) muda", "properties": { "event_type": { "type": "string", "enum": ["hsm.status"], "description": "Tipo de evento, sempre 'hsm.status' para atualizações de estado de HSM" }, "event_id": { "type": "string", "description": "Identificador único del evento" }, "timestamp": { "type": "string", "format": "date-time", "description": "Marca de tiempo del evento en formato ISO 8601" }, "status": { "type": "string", "enum": [ "APPROVED", "REJECTED", "PAUSED", "DISABLED", "PENDING_DELETION" ], "description": "Novo estado do HSM" }, "name": { "type": "string", "description": "Nombre o identificador del HSM" }, "affected_conversation_ids": { "type": "array", "description": "IDs das conversas afetadas pela mudança de estado", "items": { "type": "integer", "description": "ID de uma conversa afetada" } } } }, "DeploymentFailureEvent": { "title": "deployment.failure", "type": "object", "required": [ "event_type", "event_id", "timestamp", "failure_reason", "user", "conversation_id", "failed_at", "user_session_keys" ], "description": "Evento que é disparado quando ocorre uma falha na implantação de uma conversa", "properties": { "event_type": { "type": "string", "enum": ["deployment.failure"], "description": "Tipo de evento, sempre 'deployment.failure' para falhas na implantação" }, "event_id": { "type": "string", "description": "Identificador único del evento" }, "timestamp": { "type": "string", "format": "date-time", "description": "Marca de tiempo del evento en formato ISO 8601" }, "failure_reason": { "type": "string", "enum": [ "FAILURE", "FAILURE_BY_HUMAN_HANDOVER", "REVOKED", "INVALID_PHONE", "FAILURE_BY_RATE_LIMIT", "COMPANY_RATE_LIMIT", "FAILURE_BY_TIER_CAPACITY", "MISSING_PARAMETER", "PARAMETER_MISMATCH", "FAILURE_BY_BLOCKED_CONTACT", "FAILURE_BY_OPTOUT_CONTACT", "INVALID_POLL", "CHARACTER_LIMIT_HEADER", "CHARACTER_LIMIT_BODY", "FAILURE_BY_DISABLED_HSM", "FAILURE_BY_SPAM_RATE_LIMIT", "FAILURE_BY_EXPERIMENT_NUMBER", "FAILURE_BY_UNABLE_TO_CONTACT" ], "description": "Razão específica da falha da implantação" }, "user": { "$ref": "#/components/schemas/UserInfo", "description": "Informação do usuário associado à implantação" }, "conversation_id": { "type": "integer", "description": "ID da conversa relacionada à implantação" }, "failed_at": { "type": "string", "format": "date-time", "description": "Marca de tempo em que ocorreu a falha" }, "user_session_keys": { "type": "array", "description": "Claves de sesión del usuario recopiladas durante la conversación", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } } } }, "AgentTag": { "type": "object", "description": "Equipe (tag) à qual o agente pertence.", "properties": { "id": { "type": "integer", "description": "Identificador da equipe.", "example": 12 }, "name": { "type": "string", "description": "Nome da equipe.", "example": "Default" } } }, "Agent": { "type": "object", "description": "Agente da sua conta que pode receber conversas.", "properties": { "id": { "type": "integer", "description": "Identificador do agente no Treble. É o valor recomendado para devolver do seu endpoint de atribuição.", "example": 4567 }, "first_name": { "type": "string", "description": "Nome do agente.", "example": "Andrea" }, "last_name": { "type": "string", "description": "Sobrenome do agente.", "example": "Soto" }, "email": { "type": "string", "description": "Email do agente, tal como está registrado no Treble. O seu endpoint de atribuição também pode devolvê-lo em vez do `id`.", "example": "andrea.soto@suaempresa.com" }, "tags": { "type": "array", "description": "Equipes às quais o agente pertence.", "items": { "$ref": "#/components/schemas/AgentTag" } } } }, "AgentAssignationContact": { "type": "object", "description": "Informações do contato que está na conversa.", "properties": { "treble_id": { "type": "string", "description": "Identificador do contato no Treble.", "example": "5215512345678" }, "name": { "type": "string", "nullable": true, "description": "Nome do contato.", "example": "Andrea Soto" }, "country_code": { "type": "string", "nullable": true, "description": "Código do país. Pode ser `null` em contatos que só existem como usuário da Meta.", "example": "52" }, "cellphone": { "type": "string", "nullable": true, "description": "Número de celular sem o código do país. Pode ser `null` em contatos que só existem como usuário da Meta.", "example": "5512345678" }, "business_scope_id": { "type": "string", "nullable": true, "description": "Identificador do contato dentro do escopo do seu negócio na Meta.", "example": "1029384756" }, "username": { "type": "string", "nullable": true, "description": "Usuário da Meta do contato, quando aplicável.", "example": null } } }, "AgentAssignationCrmObject": { "type": "object", "description": "Registro do CRM associado ao contato.", "properties": { "entity": { "type": "string", "description": "Tipo de objeto no CRM, por exemplo `Contact`, `Account` ou `Lead`.", "example": "Contact" }, "id": { "type": "string", "description": "Identificador do registro no seu CRM.", "example": "0035f00000ABCDEqAO" } } }, "AgentAssignationChannel": { "type": "object", "description": "Canal pelo qual a conversa entrou.", "properties": { "phone_number_id": { "type": "string", "description": "Identificador da linha de WhatsApp que recebeu a conversa.", "example": "1234567890" } } }, "AgentAssignationMetadata": { "type": "object", "description": "Contexto do fluxo e do bloco que originou a chamada.", "properties": { "poll_id": { "type": "integer", "description": "Identificador da conversa (fluxo) do Treble.", "example": 4321 }, "node_id": { "type": "string", "description": "Identificador do bloco de Métodos de transferência que originou a chamada.", "example": "a1b2c3" }, "tag": { "type": "string", "nullable": true, "description": "Equipe (tag) selecionada no bloco.", "example": "Comercial" }, "language": { "type": "string", "nullable": true, "description": "Idioma da conversa.", "example": "es" } } }, "AgentAssignationRequest": { "type": "object", "description": "Corpo que o Treble envia ao seu endpoint para que você decida qual agente recebe a conversa.", "properties": { "company_id": { "type": "integer", "description": "Identificador da sua empresa no Treble.", "example": 1234 }, "survey_user_id": { "type": "integer", "description": "Identificador da sessão do contato na conversa.", "example": 567890 }, "contact": { "$ref": "#/components/schemas/AgentAssignationContact" }, "crm_type": { "type": "string", "nullable": true, "description": "CRM com o qual a sua conta está integrada, por exemplo `salesforce` ou `hubspot`. É `null` se a conta não tiver integração de CRM.", "example": "salesforce" }, "crm_objects": { "type": "array", "description": "Registros do CRM associados ao contato. Um array vazio significa que o contato ainda não está associado a nenhum registro.", "items": { "$ref": "#/components/schemas/AgentAssignationCrmObject" } }, "channel": { "$ref": "#/components/schemas/AgentAssignationChannel" }, "metadata": { "$ref": "#/components/schemas/AgentAssignationMetadata" } } }, "AgentAssignationResponse": { "type": "object", "description": "Resposta que o seu servidor deve devolver indicando o agente que receberá a conversa. Use `agent_id` ou `agent_email`.", "properties": { "agent_id": { "type": "integer", "description": "Identificador do agente no Treble. É a opção recomendada: é um identificador estável que nunca muda, mesmo se o email do agente for atualizado.", "example": 4567 }, "agent_email": { "type": "string", "description": "Email do agente, exatamente como está registrado no Treble. Também é suportado; se você enviar ambos os campos, `agent_email` tem precedência.", "example": "andrea.soto@suaempresa.com" } } } } }, "tags": [ { "name": "Webhooks", "description": "Endpoints que o Treble chamará no seu servidor. Estes não são endpoints reais que você possa chamar, mas uma representação dos webhooks que o Treble invocará no seu sistema." } ] }