# Home: English Documentation ## Documentation - [English / Documentation / User Guide (149 pages)](https://help.treble.ai/_llms/en/documentation/user-guide.md): Documentation for English / Documentation / User Guide. ### Welcome #### Home - [Welcome](https://help.treble.ai/en/home.md): Welcome to Treble.ai ### API Reference #### Introduction to API - [Introduction](https://help.treble.ai/en/api-reference/intro/intro.md): This is an introduction to the Treble API. Here you will find information about the available endpoints and how to interact with them. The Treble API adds functionality to the Treble platform so you can implement more complex use cases. - [API Key and Webhook Headers](https://help.treble.ai/en/api-reference/intro/api-key.md): To interact with the Treble API, you will need an API key. This key will allow you to authenticate your requests to the API and access the available endpoints. Learn how to obtain your API key in this article. #### API - [Deploy a conversation flow](https://help.treble.ai/en/api-reference/endpoints/deploy.md): 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. - [Get all conversations](https://help.treble.ai/en/api-reference/endpoints/get-convos.md): This endpoint allows you to get all conversations (flows) that belong to your company. - [Get all sessions](https://help.treble.ai/en/api-reference/endpoints/get-sessions.md): 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. - [Get session history](https://help.treble.ai/en/api-reference/endpoints/get-session-history.md): This endpoint, given a session ID, returns the complete message history for that specific session. - [Update a session](https://help.treble.ai/en/api-reference/endpoints/session-update.md): 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. - [Get your company's agents](https://help.treble.ai/en/api-reference/endpoints/get-agents.md): 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. #### Webhooks - [Introduction to webhooks](https://help.treble.ai/en/api-reference/webhooks/intro.md): Webhooks are a way to receive real-time notifications about specific events on the Treble platform. Learn how to configure and use webhooks to receive real-time notifications in this article. ##### Conversation Editor - [Message Read and Delivery Webhooks](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/delivered-read.md): Message read and delivery webhooks are triggered when a user reads or receives a message. Learn how to configure them in this article. - [Message Delivery Webhook Request Body](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/delivered-api.md): 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. - [Message Read Webhook Request Body](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/read-api.md): 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. - [Message Response Webhook](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/message-response.md): Message response webhooks are triggered when a user responds to a message. Learn how to configure them in this article. - [Stop Treble conversation and wait for your server response](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/request-trigger.md): Normally, Treble expects your server's response to a webhook to be less than 10 seconds. If you need more time, you can stop the Treble conversation and wait for your server response with the `[REQUEST_TRIGGER]` option. Learn how to configure it in this article. - [Message Response Webhook Request Body](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/message-response-api.md): 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. - [Condition Node Webhook Request Body](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/condition-node-api.md): 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. - [Timeout Webhook Request Body (Alternate Flow)](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/timeout-api.md): 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. - [Opt-out Webhook](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/opt-out.md): Opt-out webhooks are triggered when a user opts not to receive more messages. Learn how to configure them in this article. - [Opt-out Webhook Request Body](https://help.treble.ai/en/api-reference/webhooks/conversation-editor/opt-out-api.md): 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. ##### Webhook Center - [Introduction to Webhooks](https://help.treble.ai/en/api-reference/webhooks/webhook-center/intro.md): Webhooks in Treble allow you to receive real-time notifications about important platform events, such as HSM state changes, session closures, or deployment failures. - [HSM Template State Change Webhook](https://help.treble.ai/en/api-reference/webhooks/webhook-center/hsm-change-state.md): The HSM Template state change webhook is triggered when Meta changes the state of an HSM Template. Learn how to configure them in this article. - [Conversation Close Webhook](https://help.treble.ai/en/api-reference/webhooks/webhook-center/conversation-closed.md): The conversation close webhook is triggered when a customer closes a conversation. Learn how to configure them in this article. - [Deployment Failure Webhook](https://help.treble.ai/en/api-reference/webhooks/webhook-center/deployment-failure.md): The deployment failure webhook is triggered when an error occurs during the conversation deployment process. Learn how to configure and handle it in this article. - [Webhook Request Examples](https://help.treble.ai/en/api-reference/webhooks/webhook-center/api-example.md): 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. ##### API Assignment - [Agent assignment webhook](https://help.treble.ai/en/api-reference/webhooks/api-assignation/intro.md): When you use the API destination of the Transfer Methods block, Treble calls your endpoint so your own system can decide which agent should receive the conversation. Learn the request and response contract here. - [Assignment webhook reference](https://help.treble.ai/en/api-reference/webhooks/api-assignation/reference.md): 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. #### Editor - [Multimedia Variable](https://help.treble.ai/en/api-reference/editor/media.md): Learn how to configure multimedia variables in your conversation flows. This will allow you to add images, videos, audio, and attachments and send them dynamically in your conversations. - [Location Variable](https://help.treble.ai/en/api-reference/editor/location.md): Learn how to configure variable location in your conversation flows. This will allow you to add location dynamically in your conversations. #### Guides and Tutorials - [Integrate Your Own AI in Treble](https://help.treble.ai/en/api-reference/guides/your-ai.md): Learn how to integrate your own AI in Treble so it can answer your user's questions. ## OpenAPI Specs - [treble-api-en](/open-api-files/treble-api-en.json)