{ "openapi": "3.0.1", "info": { "title": "Treble Poll API", "description": "Documentation for the poll deployment endpoint in Treble", "version": "1.0.0" }, "servers": [ { "url": "https://main.treble.ai", "description": "Main Treble server" }, { "url": "https://yourdomain.com", "description": "Example server for implementing webhooks. This represents YOUR server where you must implement the endpoints that Treble will call." } ], "paths": { "/deployment/api/poll/{poll_id}": { "post": { "summary": "Deploy a poll to specific users", "description": "This endpoint allows you to deploy a conversation to a list of users defined by their phone number and country code. It also allows you to schedule deployments for a future date.", "parameters": [ { "name": "poll_id", "in": "path", "required": true, "description": "ID of the poll you want to deploy", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "description": "Authorization API Key. Can be obtained at https://app.treble.ai/en/dashboard/settings/developers", "schema": { "type": "string" }, "example": "API_KEY" }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": ["application/json"] } } ], "requestBody": { "description": "Information of the users to whom the poll will be deployed", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["users"], "properties": { "users": { "type": "array", "description": "List of users to whom the poll will be deployed", "items": { "type": "object", "required": [ "cellphone", "country_code", "user_session_keys" ], "properties": { "cellphone": { "type": "string", "description": "User's phone number without the country code (e.g., '3051234567')" }, "country_code": { "type": "string", "description": "Country code with the + symbol (e.g., '+57')" }, "user_session_keys": { "type": "array", "description": "Variables that can be replaced in question texts or delivered when a webhook is called. For multi-channel companies, you can include the 'deployment_squad' key to select which phone number will perform the deployment.", "items": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string", "description": "Name of the variable. Special values include 'deployment_squad' to select which phone number will perform the deployment." }, "value": { "type": "string", "description": "Value of the variable. For 'deployment_squad', the value must be 'DS_[CELLPHONE]'." } } } }, "deployment_eta": { "type": "integer", "description": "UNIX UTC timestamp to schedule the deployment for a future date (optional). Example: 1615823201 (March 15, 2021, 3:46:41 PM UTC)" } } } } } }, "examples": { "Basic example": { "value": { "users": [ { "cellphone": "3051234567", "country_code": "+57", "user_session_keys": [ { "key": "name", "value": "John" }, { "key": "TransID", "value": "12345" }, { "key": "schoolname", "value": "Redschool" } ] } ] } }, "Example with deployment_eta": { "value": { "users": [ { "cellphone": "3051234567", "country_code": "+57", "user_session_keys": [ { "key": "name", "value": "Jhon" } ], "deployment_eta": 1615823201 } ] } }, "Example with deployment_squad": { "value": { "users": [ { "cellphone": "3051234567", "country_code": "+57", "user_session_keys": [ { "key": "name", "value": "Jhon" }, { "key": "deployment_squad", "value": "DS_[CELLPHONE]" } ] } ] } } } } } }, "responses": { "200": { "description": "The poll was deployed correctly", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" }, "id": { "type": "string", "description": "Deployment ID" }, "batch_id": { "type": "string", "description": "Batch deployment ID" }, "new_last_scheduleded_deployment": { "type": "string", "format": "date-time", "description": "Date and time of the last scheduled deployment" }, "conversations_id": { "type": "array", "items": { "type": "string" }, "description": "List of IDs of the created conversations" } } }, "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": "Error in the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } }, "401": { "description": "Unauthorized. Invalid or missing API Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } }, "404": { "description": "Poll not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } } } } }, "/poll/api/all": { "get": { "summary": "Get all conversations (flows) from your company", "description": "This endpoint allows you to get all conversations (flows) that belong to your company.", "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Authorization API Key. Can be obtained at https://app.treble.ai/en/dashboard/settings/developers", "schema": { "type": "string" }, "example": "API_KEY" } ], "responses": { "200": { "description": "List of conversations obtained correctly", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Conversation" } }, "example": [ { "id": 1, "name": "First conversation" }, { "id": 2, "name": "CRM integration" } ] } } }, "401": { "description": "Unauthorized. Invalid or missing API Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } } } } }, "/treble-webhooks": { "post": { "summary": "Webhook - Treble Events", "description": "This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/treble-webhooks). Treble will call this webhook for different types of events. You must configure the URL of this webhook in the Treble admin panel.", "tags": ["Webhooks"], "servers": [ { "url": "https://{webhookUrl}", "description": "Enter your webhook endpoint URL", "variables": { "webhookUrl": { "default": "yourdomain.com", "description": "URL of your server where the webhook will be implemented" } } } ], "requestBody": { "description": "Event information. The type of event is determined by the 'event_type' field.", "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": "HSM Status Update", "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": "Conversation closed", "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": "Hello {{1}}, welcome to our customer service.", "answers": [ { "message": "Thank you for the welcome" } ], "header": { "type": "image", "url": "https://example.com/logo.jpg" }, "footer": "Reply to this message to continue", "buttons": { "type": "actions", "options": [ { "type": "quick_reply", "message": "I need help" }, { "type": "call_to_action", "subtype": "website", "url": "https://example.com/catalog", "message": "View catalog" } ] } } } }, "deployment.failure": { "summary": "Deployment failure", "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": "Successful response", "content": { "application/json": { "schema": { "type": "object", "description": "JSON object with the confirmation of reception. The service must respond in less than 5 seconds." } } } } } } }, "/devapi/poll/{poll_id}/sessions": { "get": { "summary": "Get session metadata from a poll", "description": "This endpoint, given a poll ID, returns the metadata of all sessions in a paginated manner. By default, it brings the first 1000 records from the current year. Optional parameters can be used to control the date range and pagination.", "parameters": [ { "name": "poll_id", "in": "path", "required": true, "description": "ID of the poll from which you want to obtain the sessions", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "description": "Authorization API Key. Can be obtained at https://app.treble.ai/en/dashboard/settings/developers", "schema": { "type": "string" }, "example": "API_KEY" }, { "name": "since", "in": "query", "required": false, "description": "Timestamp UNIX UTC for the start date of the range to query", "schema": { "type": "integer" } }, { "name": "until", "in": "query", "required": false, "description": "Timestamp UNIX UTC for the end date of the range to query", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Integer between 1 and 10,000 that indicates the number of sessions to recover", "schema": { "type": "integer", "minimum": 1, "maximum": 10000 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor returned in the 'next_id' property of the previous response", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of session metadata obtained correctly", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the session" }, "created_at": { "type": "string", "format": "date-time", "description": "Date and time when the session was created" }, "finished_at": { "type": "string", "format": "date-time", "description": "Date and time when the session was finished" }, "user": { "type": "object", "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" } } } } }, "description": "List of session metadata" }, "next_id": { "type": "string", "description": "Cursor to get the next page of results" } } }, "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": "Unauthorized. Invalid or missing API Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } }, "404": { "description": "Poll not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } } } } }, "/devapi/session/{session_id}/history": { "get": { "summary": "Get message history from a session", "description": "This endpoint, given a session ID, returns the complete message history for that specific session.", "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "ID of the session from which you want to obtain the message history", "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "required": true, "description": "Authorization API Key. Can be obtained at https://app.treble.ai/en/dashboard/settings/developers", "schema": { "type": "string" }, "example": "API_KEY" } ], "responses": { "200": { "description": "Message history obtained correctly", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of entry in the history", "example": "MESSAGE" }, "message": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of message", "example": "TEXT" }, "sender": { "type": "string", "description": "Sender of the message", "example": "USER" }, "text": { "type": "string", "description": "Content of the message" }, "file_url": { "type": "string", "nullable": true, "description": "URL of the attached file (if it exists)" }, "created_at": { "type": "integer", "description": "Timestamp UNIX UTC of message creation" }, "delivered_at": { "type": "integer", "nullable": true, "description": "Timestamp UNIX UTC of message delivery" }, "read_at": { "type": "integer", "nullable": true, "description": "Timestamp UNIX UTC of message reading" }, "extra": { "type": "object", "nullable": true, "description": "Additional information of the message" } } } } } }, "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": "Unauthorized. Invalid or missing API Key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } } } } }, "/session/{session_external_id}/update": { "post": { "summary": "Update user session and continue conversation", "description": "This endpoint allows you to update the session keys of a specific user and continue the conversation started previously. The webhook triggered by the user's first response will provide the session_external_id needed for this request.", "parameters": [ { "name": "session_external_id", "in": "path", "required": true, "description": "External ID of the user's session. Obtained from the 'session_external_id' field in the webhook response triggered by the user's first interaction.", "schema": { "type": "string" }, "example": "f33b4734a2e5db671b59877ed3f662ec1f6332a0418c25de4868e35a" }, { "name": "content-type", "in": "header", "required": true, "schema": { "type": "string", "enum": ["application/json"] } } ], "requestBody": { "description": "Information of the session keys to be updated", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["user_session_keys"], "properties": { "user_session_keys": { "type": "array", "description": "List of user session keys to be updated", "items": { "$ref": "#/components/schemas/UserSessionKey" } } } }, "example": { "user_session_keys": [ { "key": "order", "value": "1 Cheeseburger, 2 Sodas" } ] } } } }, "responses": { "200": { "description": "Session updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Confirmation message" }, "session_id": { "type": "string", "description": "ID of the updated session" } } }, "example": { "message": "Session updated successfully", "session_id": "f33b4734a2e5db671b59877ed3f662ec1f6332a0418c25de4868e35a" } } } }, "400": { "description": "Error in the request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } }, "404": { "description": "Session not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Error description" } } } } } } } } }, "/webhooks/on-delivered": { "post": { "summary": "Webhook - When a message is delivered", "description": "This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/webhooks/on-delivered). Treble will call this webhook when a message is delivered to the user. You must configure the URL of this webhook in the Treble admin panel.", "tags": ["Webhooks"], "servers": [ { "url": "https://yourdomain.com", "description": "Your server where you must implement this webhook" } ], "requestBody": { "description": "Information of the delivery event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveredEvent" }, "example": { "country_code": "+57", "cellphone": "3176477608", "session_id": "d2fa98d29a2670dfa119335df1b0371720d674f1677302aba228876a", "conversation_id": 34820, "question": { "type": "open", "text": "Hello! Good morning. I hope everything is well. Would you like to continue our conversation to resolve all your problems and concerns?" }, "sent_at": "2021-06-22 15:19:06.473256", "sent_text": "Hello! Good morning. I hope everything is well. Would you like to continue our conversation to resolve all your problems and concerns?", "user_session_keys": [], "delivered_at": "2021-06-22 15:19:08" } } } }, "responses": { "200": { "description": "Response to update or add information to the session", "content": { "application/json": { "schema": { "type": "object", "description": "JSON object with the new information that will be replaced or added to the session for future use. The service must respond in less than 10 seconds." } } } } } } }, "/webhooks/on-read": { "post": { "summary": "Webhook - When a message is read", "description": "This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/webhooks/on-read). Treble will call this webhook when a message is read by the user. You must configure the URL of this webhook in the Treble admin panel.", "tags": ["Webhooks"], "servers": [ { "url": "https://yourdomain.com", "description": "Your server where you must implement this webhook" } ], "requestBody": { "description": "Information of the read event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadEvent" }, "example": { "country_code": "+57", "cellphone": "3176477608", "session_id": "d2fa98d29a2670dfa119335df1b0371720d674f1677302aba228876a", "conversation_id": 34820, "question": { "type": "open", "text": "Hello! Good morning. I hope everything is well. Would you like to continue our conversation to resolve all your problems and concerns?" }, "sent_at": "2021-06-22 15:19:06.473256", "sent_text": "Hello! Good morning. I hope everything is well. Would you like to continue our conversation to resolve all your problems and concerns?", "user_session_keys": [], "read_at": "2021-06-22 15:19:08" } } } }, "responses": { "200": { "description": "Response to update or add information to the session", "content": { "application/json": { "schema": { "type": "object", "description": "JSON object with the new information that will be replaced or added to the session for future use. The service must respond in less than 10 seconds." } } } } } } }, "/webhooks/on-response": { "post": { "summary": "Webhook - When a user responds to a question", "description": "This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/webhooks/on-response). Treble will call this webhook when a user responds to a question in the conversation. You must configure the URL of this webhook in the Treble admin panel.", "tags": ["Webhooks"], "servers": [ { "url": "https://yourdomain.com", "description": "Your server where you must implement this webhook" } ], "requestBody": { "description": "Information of the response event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResponseEvent" }, "example": { "country_code": "+57", "cellphone": "3161234567", "session_id": "1234", "conversation_id": "5678", "question": { "type": "closed", "text": "conversation-question-text", "answers": [{ "text": "answer-text" }] }, "sent_at": "2019-01-01 00:00:00", "responded_at": "2019-01-01 00:00:00", "sent_text": "text-sent-to-user", "actual_response": "Yes I need it", "classified_answer": { "text": "answer-text" }, "user_session_keys": [ { "key": "name", "value": "John", "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": "Response to update or add information to the session", "content": { "application/json": { "schema": { "type": "object", "description": "JSON object with the new information that will be replaced or added to the session for future use. The service must respond in less than 10 seconds." } } } } } } }, "/webhooks/on-optout": { "post": { "summary": "Webhook - When a user opts out", "description": "This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/webhooks/on-optout). Treble will call this webhook when a user decides to opt out or exit the conversation. You must configure the URL of this webhook in the Treble admin panel.", "tags": ["Webhooks"], "servers": [ { "url": "https://yourdomain.com", "description": "Your server where you must implement this webhook" } ], "requestBody": { "description": "Information of the opt-out event", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptOutEvent" }, "example": { "country_code": "+57", "cellphone": "3176477608", "session_id": "85b398ef5bcb20c355f3710c4509349784c907673c9118fb7a89c7a8", "conversation_id": 54263, "question": { "type": "closed", "text": "Hi! Thanks for attending our webinar today. We would like to have a feedback about our session and we would be very grateful if you could help us with that. ", "answers": [ {"text": "Sure"}, {"text": "No, thanks"}, {"text": "DEFAULT"} ] }, "sent_at": "2021-10-22 00:15:39.044704", "sent_text": "Hi! Thanks for attending our webinar today. We would like to have a feedback about our session and we would be very grateful if you could help us with that. \n1) Sure\n2) No, thanks\n3) DEFAULT", "user_session_keys": [], "classified_answer": { "text": "No, thanks" }, "reason": "OPTOUT" } } } }, "responses": { "200": { "description": "Response to update or add information to the session", "content": { "application/json": { "schema": { "type": "object", "description": "JSON object with the new information that will be replaced or added to the session for future use. The service must respond in less than 10 seconds." } } } } } } }, "/webhooks/on-condition": { "post": { "summary": "Webhook - When a conditional node is evaluated", "description": "This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/webhooks/on-condition). Treble will call this webhook when a conditional node is evaluated in the conversation. You must configure the URL of this webhook in the Treble admin panel.", "tags": ["Webhooks"], "servers": [ { "url": "https://yourdomain.com", "description": "Your server where you must implement this webhook" } ], "requestBody": { "description": "Information of the condition evaluation event", "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": "Response to update or add information to the session", "content": { "application/json": { "schema": { "type": "object", "description": "JSON object with the new information that will be replaced or added to the session for future use. The service must respond in less than 10 seconds." } } } } } } }, "/webhooks/on-timeout": { "post": { "summary": "Webhook - When a timeout occurs in the conversation", "description": "This endpoint must be implemented on YOUR server (e.g., https://yourdomain.com/webhooks/on-timeout). Treble will call this webhook when a timeout occurs in the conversation (the user does not respond within the established time). You must configure the URL of this webhook in the Treble admin panel.", "tags": ["Webhooks"], "servers": [ { "url": "https://yourdomain.com", "description": "Your server where you must implement this webhook" } ], "requestBody": { "description": "Information of the timeout event", "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": "Hello world" }, "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": "Response to update or add information to the session", "content": { "application/json": { "schema": { "type": "object", "description": "JSON object with the new information that will be replaced or added to the session for future use. The service must respond in less than 10 seconds." } } } } } } }, "/agent/company/agents": { "get": { "summary": "Get your company's agents", "description": "Returns the agents in your account that can receive conversations. Use it to find out each agent's `id` and `email`, which are the values you must return from your endpoint when using the **API** destination of the Transfer Methods block.\n\nOnly **active** agents are returned, so any agent in the response can receive a conversation.\n\nThis endpoint lives on the agent platform host, `agent-api.treble.ai`, and not on `main.treble.ai`.", "servers": [ { "url": "https://agent-api.treble.ai", "description": "Treble agent platform host" } ], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Authorization API Key. It can be obtained at https://app.treble.ai/en/dashboard/settings/developers", "schema": { "type": "string" }, "example": "API_KEY" } ], "responses": { "200": { "description": "Agent list retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Agent" } }, "example": [ { "id": 4567, "first_name": "Andrea", "last_name": "Soto", "email": "andrea.soto@yourcompany.com", "tags": [ { "id": 12, "name": "Default" }, { "id": 18, "name": "Comercial" } ] } ] } } } } } }, "/webhooks/on-agent-assignation": { "post": { "summary": "Webhook - Decide which agent receives the conversation", "description": "This endpoint must be implemented on YOUR server (for example: https://yourdomain.com/webhooks/on-agent-assignation). Treble will call it when a conversation reaches a **Transfer Methods** block configured with the **API** destination, so your system can decide which agent should receive the chat.\n\nThe URL is configured in the block itself, inside the conversation editor. If you enable Token / API Key authentication, Treble will include your token in the `Authorization` header with the format `Bearer YOUR_TOKEN`.\n\nYou must respond in less than 10 seconds. If your server doesn't respond in time, returns a status code other than 200, or returns an agent that can't receive the conversation, Treble will apply the fallback method configured in the main platform.", "tags": [ "Webhooks" ], "servers": [ { "url": "https://yourdomain.com", "description": "Your server where you must implement this webhook" } ], "parameters": [ { "name": "Authorization", "in": "header", "required": false, "description": "Only if you configured Token / API Key authentication in the block. Treble sends the token with the format `Bearer YOUR_TOKEN`.", "schema": { "type": "string" }, "example": "Bearer YOUR_TOKEN" } ], "requestBody": { "description": "Context of the contact and the conversation that Treble sends to your 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": "The agent Treble must assign the conversation to. Return `agent_id` (recommended) or `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": "Name of the variable. Special values include 'deployment_squad' to select which phone number will perform the deployment in multi-channel companies." }, "value": { "type": "string", "description": "Value of the variable. For 'deployment_squad', the value must be 'DS_[CELLPHONE]'." } } }, "User": { "type": "object", "required": ["cellphone", "country_code", "user_session_keys"], "properties": { "cellphone": { "type": "string", "description": "User's phone number without the country code (e.g.: '3051234567')" }, "country_code": { "type": "string", "description": "Country code with the + symbol (e.g.: '+57')" }, "user_session_keys": { "type": "array", "description": "Variables that can be replaced in the question texts or delivered when calling a webhook. For multi-channel companies, it can include the 'deployment_squad' key to select which phone number will perform the deployment.", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "deployment_eta": { "type": "integer", "description": "Timestamp UNIX UTC to schedule the deployment for a future date (optional). Example: 1615823201 (March 15, 2021, 3:46:41 PM UTC)" } } }, "DeploymentSquadKey": { "type": "object", "description": "Special key for multi-channel companies that allows selecting which phone number will perform the deployment.", "required": ["key", "value"], "properties": { "key": { "type": "string", "enum": ["deployment_squad"], "description": "Key to specify a phone number that will perform the deployment." }, "value": { "type": "string", "pattern": "^DS_\\[CELLPHONE\\]$", "description": "Value that must follow the format 'DS_[CELLPHONE]'. It is possible to add several deployment squads so that several phone numbers can perform the deployment." } } }, "Conversation": { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "integer", "description": "Unique ID of the conversation" }, "name": { "type": "string", "description": "Name of the conversation" } } }, "Question": { "type": "object", "required": ["type", "text"], "properties": { "type": { "type": "string", "description": "Type of question", "example": "open" }, "text": { "type": "string", "description": "Text of the question" } } }, "ClosedQuestion": { "type": "object", "required": ["type", "text", "answers"], "properties": { "type": { "type": "string", "description": "Type of question", "example": "closed" }, "text": { "type": "string", "description": "Text of the question" }, "answers": { "type": "array", "description": "Possible answers for the closed question", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Text of the answer" } } } } } }, "Answer": { "type": "object", "required": ["text"], "properties": { "text": { "type": "string", "description": "Text of the answer" } } }, "ExtendedUserSessionKey": { "type": "object", "required": ["key", "value"], "properties": { "key": { "type": "string", "description": "Name of the variable" }, "value": { "type": "string", "description": "Value of the variable" }, "type": { "type": "string", "nullable": true, "description": "Type of the variable. Can be null or a specific type like 'location'." } } }, "DeliveredEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "sent_at", "sent_text", "delivered_at" ], "description": "Event that is triggered when a message is delivered to the user", "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" }, "session_id": { "type": "string", "description": "ID of the user's session" }, "conversation_id": { "type": "integer", "description": "ID of the conversation" }, "question": { "$ref": "#/components/schemas/Question" }, "sent_at": { "type": "string", "format": "date-time", "description": "Date and time when the message was sent" }, "sent_text": { "type": "string", "description": "Text of the sent message" }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation or provided during the deployment", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "delivered_at": { "type": "string", "format": "date-time", "description": "Date and time when the message was delivered to the user" } } }, "ReadEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "sent_at", "sent_text", "read_at" ], "description": "Event that is triggered when a message is read by the user", "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" }, "session_id": { "type": "string", "description": "ID of the user's session" }, "conversation_id": { "type": "integer", "description": "ID of the conversation" }, "question": { "$ref": "#/components/schemas/Question" }, "sent_at": { "type": "string", "format": "date-time", "description": "Date and time when the message was sent" }, "sent_text": { "type": "string", "description": "Text of the sent message" }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation or provided during the deployment", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "read_at": { "type": "string", "format": "date-time", "description": "Date and time when the message was read by the user" } } }, "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": "Event that is triggered when a user responds to a question in the conversation", "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" }, "session_id": { "type": "string", "description": "ID of the user's session" }, "conversation_id": { "type": "string", "description": "ID of the conversation" }, "question": { "$ref": "#/components/schemas/ClosedQuestion" }, "sent_at": { "type": "string", "format": "date-time", "description": "Date and time when the question was sent" }, "responded_at": { "type": "string", "format": "date-time", "description": "Date and time when the user responded to the question" }, "sent_text": { "type": "string", "description": "Text sent to the user" }, "actual_response": { "type": "string", "description": "Literal response provided by the user" }, "classified_answer": { "$ref": "#/components/schemas/Answer", "description": "Classified answer based on the user's response" }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation or provided during the deployment", "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": "Event that is triggered when a user decides to opt out or exit the conversation", "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" }, "session_id": { "type": "string", "description": "ID of the user's session" }, "conversation_id": { "type": "integer", "description": "ID of the conversation" }, "question": { "$ref": "#/components/schemas/ClosedQuestion" }, "sent_at": { "type": "string", "format": "date-time", "description": "Date and time when the question was sent" }, "sent_text": { "type": "string", "description": "Text sent to the user" }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation or provided during the deployment", "items": { "$ref": "#/components/schemas/UserSessionKey" } }, "classified_answer": { "$ref": "#/components/schemas/Answer", "description": "Classified answer based on the user's response" }, "reason": { "type": "string", "description": "Reason for the user's exit, in this case 'OPTOUT' to indicate that the user decided to opt out", "enum": ["OPTOUT"] } } }, "Variable": { "type": "object", "required": ["name", "value"], "properties": { "name": { "type": "string", "description": "Name of the variable that is evaluated in the condition" }, "value": { "type": "string", "description": "Current value of the variable" } } }, "Condition": { "type": "object", "required": ["operator", "value"], "properties": { "operator": { "type": "string", "description": "Operator used to evaluate the condition (e.g.: 'EQ' for equal, 'GT' for greater than, etc.)", "enum": ["EQ", "GT", "LT", "GTE", "LTE", "NEQ"] }, "value": { "type": "string", "description": "Value against which the variable is compared" } } }, "ConditionEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "variable", "condition", "user_session_keys" ], "description": "Event that is triggered when a conditional node is evaluated in the conversation", "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" }, "session_id": { "type": "string", "description": "ID of the user's session" }, "conversation_id": { "type": "integer", "description": "ID of the conversation" }, "variable": { "$ref": "#/components/schemas/Variable", "description": "Variable that is evaluated in the condition" }, "condition": { "$ref": "#/components/schemas/Condition", "description": "Condition that is evaluated" }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation or provided during the deployment", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } } } }, "TimeoutEvent": { "type": "object", "required": [ "country_code", "cellphone", "session_id", "conversation_id", "question", "timeout_at", "user_session_keys" ], "description": "Event that is triggered when a timeout occurs in the conversation (the user does not respond within the established time)", "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" }, "session_id": { "type": "string", "description": "ID of the user's session" }, "conversation_id": { "type": "integer", "description": "ID of the conversation" }, "question": { "$ref": "#/components/schemas/Question", "description": "Question that did not receive a response in time" }, "timeout_at": { "type": "string", "format": "date-time", "description": "Date and time when the timeout occurred" }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation or provided during the deployment", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } } } }, "Session": { "type": "object", "required": ["external_id", "closed_at"], "properties": { "external_id": { "type": "string", "description": "Unique external ID of the session" }, "closed_at": { "type": "string", "format": "date-time", "description": "Date and time when the conversation was closed" } } }, "UserInfo": { "type": "object", "required": ["country_code", "cellphone"], "properties": { "country_code": { "type": "string", "description": "Country code of the user" }, "cellphone": { "type": "string", "description": "User's phone number without the country code" } } }, "CompanyInfo": { "type": "object", "required": ["id", "cellphone"], "properties": { "id": { "type": "integer", "description": "ID of the company in Treble" }, "cellphone": { "type": "string", "description": "Company's phone number" } } }, "TextMessage": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "Content of the text message" } } }, "HSMMessage": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "Content of the HSM message" } } }, "MediaContent": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "description": "URL of the multimedia file" }, "message": { "type": "string", "description": "Photo or description of the multimedia content" } } }, "LocationContent": { "type": "object", "required": ["latitude", "longitude"], "properties": { "latitude": { "type": "number", "format": "float", "description": "Latitude of the location" }, "longitude": { "type": "number", "format": "float", "description": "Longitude of the location" } } }, "Message": { "type": "object", "required": ["sender", "type", "created_at", "delivered_at", "read_at"], "properties": { "sender": { "type": "string", "description": "Who sent the message (user or company)", "enum": ["user", "company"] }, "type": { "type": "string", "description": "Type of message", "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": "Date and time when the message was created" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time when the message was delivered" }, "read_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Date and time when the message was read" } } }, "HSMHeaderText": { "type": "object", "required": ["type", "message"], "properties": { "type": { "type": "string", "enum": ["text"], "description": "Type of header" }, "message": { "type": "string", "description": "Text of the header" } } }, "HSMHeaderMedia": { "type": "object", "required": ["type", "url"], "properties": { "type": { "type": "string", "enum": ["image", "video", "document"], "description": "Type of media in the header" }, "url": { "type": "string", "description": "URL of the multimedia file in the header" } } }, "HSMButtonQuickReply": { "type": "object", "required": ["type", "message"], "properties": { "type": { "type": "string", "enum": ["quick_reply"], "description": "Type of quick reply button" }, "message": { "type": "string", "description": "Text of the quick reply button" } } }, "HSMButtonOTP": { "type": "object", "required": ["type", "message"], "properties": { "type": { "type": "string", "enum": ["otp"], "description": "Type of OTP button" }, "message": { "type": "string", "description": "Text of the OTP button" } } }, "HSMButtonCallToAction": { "type": "object", "required": ["type", "message", "subtype"], "properties": { "type": { "type": "string", "enum": ["call_to_action"], "description": "Type of call to action button" }, "subtype": { "type": "string", "enum": ["website", "phone"], "description": "Subtype of call to action button" }, "url": { "type": "string", "description": "URL of the call to action button if the subtype is website" }, "phone": { "type": "string", "description": "Phone number of the call to action button if the subtype is phone" } } }, "HSMInfo": { "type": "object", "required": ["name", "text", "answers", "header", "footer", "buttons"], "properties": { "name": { "type": "string", "description": "Name or identifier of the HSM" }, "text": { "type": "string", "description": "Main text of the HSM" }, "answers": { "type": "array", "description": "Possible answers for the HSM", "items": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "description": "Text of the answer" } } } }, "header": { "oneOf": [ { "$ref": "#/components/schemas/HSMHeaderText" }, { "$ref": "#/components/schemas/HSMHeaderMedia" } ], "nullable": true, "description": "Header of the HSM (can be text or multimedia)" }, "footer": { "type": "string", "nullable": true, "description": "Footer of the HSM" }, "buttons": { "type": "object", "required": ["type", "options"], "properties": { "type": { "type": "string", "enum": ["actions", "otp"], "description": "Category of buttons" }, "options": { "type": "array", "description": "Options of buttons", "items": { "oneOf": [ { "$ref": "#/components/schemas/HSMButtonQuickReply" }, { "$ref": "#/components/schemas/HSMButtonCallToAction" }, { "$ref": "#/components/schemas/HSMButtonOTP" } ] } } }, "nullable": true, "description": "Buttons of the HSM" } } }, "ConversationClosedEvent": { "title": "session.close", "type": "object", "required": [ "event_type", "event_id", "timestamp", "session", "user", "company", "messages", "user_session_keys", "hsm" ], "description": "Event that is triggered when a conversation between a user and the company is closed", "properties": { "event_type": { "type": "string", "enum": ["session.close"], "description": "Type of event, always 'session.close' for closed conversations" }, "event_id": { "type": "string", "description": "Unique identifier of the event" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the event in ISO 8601 format" }, "session": { "$ref": "#/components/schemas/Session", "description": "Information of the closed session" }, "user": { "$ref": "#/components/schemas/UserInfo", "description": "Information of the user" }, "company": { "$ref": "#/components/schemas/CompanyInfo", "description": "Information of the company" }, "messages": { "type": "array", "description": "Messages exchanged during the conversation", "items": { "$ref": "#/components/schemas/Message" } }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } }, "hsm": { "$ref": "#/components/schemas/HSMInfo", "nullable": true, "description": "Information of the HSM that started the conversation (if applicable)" } } }, "HSMStatusUpdateEvent": { "title": "hsm.status", "type": "object", "required": [ "event_type", "event_id", "timestamp", "status", "name", "affected_conversation_ids" ], "description": "Event that is triggered when the status of an HSM (Highly Structured Message) changes", "properties": { "event_type": { "type": "string", "enum": ["hsm.status"], "description": "Type of event, always 'hsm.status' for HSM status updates" }, "event_id": { "type": "string", "description": "Unique identifier of the event" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the event in ISO 8601 format" }, "status": { "type": "string", "enum": [ "APPROVED", "REJECTED", "PAUSED", "DISABLED", "PENDING_DELETION" ], "description": "New status of the HSM" }, "name": { "type": "string", "description": "Name or identifier of the HSM" }, "affected_conversation_ids": { "type": "array", "description": "IDs of the conversations affected by the status change", "items": { "type": "integer", "description": "ID of an affected conversation" } } } }, "DeploymentFailureEvent": { "title": "deployment.failure", "type": "object", "required": [ "event_type", "event_id", "timestamp", "failure_reason", "user", "conversation_id", "failed_at", "user_session_keys" ], "description": "Event that is triggered when a failure occurs in the deployment of a conversation", "properties": { "event_type": { "type": "string", "enum": ["deployment.failure"], "description": "Type of event, always 'deployment.failure' for deployment failures" }, "event_id": { "type": "string", "description": "Unique identifier of the event" }, "timestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the event in ISO 8601 format" }, "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": "Specific reason for the deployment failure" }, "user": { "$ref": "#/components/schemas/UserInfo", "description": "Information of the user associated with the deployment" }, "conversation_id": { "type": "integer", "description": "ID of the conversation related to the deployment" }, "failed_at": { "type": "string", "format": "date-time", "description": "Timestamp when the failure occurred" }, "user_session_keys": { "type": "array", "description": "User session keys collected during the conversation", "items": { "$ref": "#/components/schemas/ExtendedUserSessionKey" } } } }, "AgentTag": { "type": "object", "description": "Team (tag) the agent belongs to.", "properties": { "id": { "type": "integer", "description": "Team identifier.", "example": 12 }, "name": { "type": "string", "description": "Team name.", "example": "Default" } } }, "Agent": { "type": "object", "description": "Agent in your account who can receive conversations.", "properties": { "id": { "type": "integer", "description": "The agent's identifier in Treble. It's the recommended value to return from your assignment endpoint.", "example": 4567 }, "first_name": { "type": "string", "description": "The agent's first name.", "example": "Andrea" }, "last_name": { "type": "string", "description": "The agent's last name.", "example": "Soto" }, "email": { "type": "string", "description": "The agent's email, as registered in Treble. Your assignment endpoint can also return it instead of the `id`.", "example": "andrea.soto@yourcompany.com" }, "tags": { "type": "array", "description": "Teams the agent belongs to.", "items": { "$ref": "#/components/schemas/AgentTag" } } } }, "AgentAssignationContact": { "type": "object", "description": "Information about the contact in the conversation.", "properties": { "treble_id": { "type": "string", "description": "The contact's identifier in Treble.", "example": "5215512345678" }, "name": { "type": "string", "nullable": true, "description": "The contact's name.", "example": "Andrea Soto" }, "country_code": { "type": "string", "nullable": true, "description": "Country code. Can be `null` for contacts that only exist as a Meta username.", "example": "52" }, "cellphone": { "type": "string", "nullable": true, "description": "Cellphone number without country code. Can be `null` for contacts that only exist as a Meta username.", "example": "5512345678" }, "business_scope_id": { "type": "string", "nullable": true, "description": "The contact's identifier within your business scope in Meta.", "example": "1029384756" }, "username": { "type": "string", "nullable": true, "description": "The contact's Meta username, when applicable.", "example": null } } }, "AgentAssignationCrmObject": { "type": "object", "description": "CRM record associated with the contact.", "properties": { "entity": { "type": "string", "description": "Object type in the CRM, for example `Contact`, `Account`, or `Lead`.", "example": "Contact" }, "id": { "type": "string", "description": "The record's identifier in your CRM.", "example": "0035f00000ABCDEqAO" } } }, "AgentAssignationChannel": { "type": "object", "description": "Channel the conversation came in through.", "properties": { "phone_number_id": { "type": "string", "description": "Identifier of the WhatsApp line that received the conversation.", "example": "1234567890" } } }, "AgentAssignationMetadata": { "type": "object", "description": "Context of the flow and the block that originated the call.", "properties": { "poll_id": { "type": "integer", "description": "Identifier of the Treble conversation (flow).", "example": 4321 }, "node_id": { "type": "string", "description": "Identifier of the Transfer Methods block that originated the call.", "example": "a1b2c3" }, "tag": { "type": "string", "nullable": true, "description": "Team (tag) selected in the block.", "example": "Comercial" }, "language": { "type": "string", "nullable": true, "description": "Language of the conversation.", "example": "es" } } }, "AgentAssignationRequest": { "type": "object", "description": "Body Treble sends to your endpoint so you can decide which agent receives the conversation.", "properties": { "company_id": { "type": "integer", "description": "Your company's identifier in Treble.", "example": 1234 }, "survey_user_id": { "type": "integer", "description": "Identifier of the contact's session in the conversation.", "example": 567890 }, "contact": { "$ref": "#/components/schemas/AgentAssignationContact" }, "crm_type": { "type": "string", "nullable": true, "description": "The CRM your account is integrated with, for example `salesforce` or `hubspot`. It's `null` if the account has no CRM integration.", "example": "salesforce" }, "crm_objects": { "type": "array", "description": "CRM records associated with the contact. An empty array means the contact isn't associated with any record yet.", "items": { "$ref": "#/components/schemas/AgentAssignationCrmObject" } }, "channel": { "$ref": "#/components/schemas/AgentAssignationChannel" }, "metadata": { "$ref": "#/components/schemas/AgentAssignationMetadata" } } }, "AgentAssignationResponse": { "type": "object", "description": "Response your server must return indicating the agent who will receive the conversation. Use `agent_id` or `agent_email`.", "properties": { "agent_id": { "type": "integer", "description": "The agent's identifier in Treble. It's the recommended option: a stable identifier that never changes, even if the agent's email is updated.", "example": 4567 }, "agent_email": { "type": "string", "description": "The agent's email, exactly as registered in Treble. Also supported; if both fields are sent, `agent_email` takes precedence.", "example": "andrea.soto@yourcompany.com" } } } } }, "tags": [ { "name": "Webhooks", "description": "Endpoints that Treble will call on your server. These are not real endpoints that you can call, but a representation of the webhooks that Treble will invoke in your system." } ] }