API reference
Send Messages
Conversations
Resources
Datum
External Support Panel
Start Conversation
curl --request POST \
--url https://gateway.jelou.ai/jelouapi/v1/external-support/{projectId}/conversations/start \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
'{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}Conversation
Start conversation
Start a new conversation with an end user
POST
/
v1
/
external-support
/
{projectId}
/
conversations
/
start
Start Conversation
curl --request POST \
--url https://gateway.jelou.ai/jelouapi/v1/external-support/{projectId}/conversations/start \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
'{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}Documentation Index
Fetch the complete documentation index at: https://docs.jelou.ai/llms.txt
Use this file to discover all available pages before exploring further.
Description
Starts a new conversation with an end user in the external support panel. Allows specifying the bot that will handle the conversation, the target user, an initial message, and assignment data for queues or agents. Upon execution, Jelou emits theconversation.start event to the webhook configured in the integration.
Endpoint
POST https://gateway.jelou.ai/jelouapi/v1/external-support/{projectId}/conversations/start
Path parameters
Unique identifier of the Jelou project from which the conversation is started.
Body parameters
Identifier of the Jelou bot that will manage the conversation.
Identifier of the end user with whom the conversation will be started.
Initial message to be sent when the conversation starts. If omitted, the conversation starts without a prior message.
Additional data associated with the conversation. Can include external identifiers, ticket numbers, or other context relevant to your system.Example:
{ "ticketId": "T-12345" }Assignment configuration for routing the conversation to a specific queue or agent.
type— Assignment type:queue,operator, orteam.target— Queue name or target agent identifier.
Authentication
All requests must include thex-api-key header with your Jelou project API key.
x-api-key: API_KEY
Request example
The following example starts a conversation with assignment to theSUPPORT queue and includes ticket metadata:
cURL
curl --request POST \
--url https://gateway.jelou.ai/jelouapi/v1/external-support/PROJECT_ID/conversations/start \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"botId": "BOT_ID",
"userId": "USER_ID",
"initialMessage": "Hello, I need help",
"metadata": { "ticketId": "T-12345" },
"assignment": { "type": "queue", "target": "SUPPORT" }
}'
Responses
| Code | Status | Description |
|---|---|---|
| 200 | OK | Conversation started successfully. |
| 401 | Unauthorized | Invalid or missing authentication credentials. |
| 404 | Not Found | Bot or user not found. |
| 422 | Bad Request | Required fields are missing or the format is invalid. |
| 500 | Internal Server Error | Internal server error. |
Response example
{
"message": [
"Conversation started successfully"
],
"statusMessage": "success",
"status": 1,
"data": {
"conversationId": "CONVERSATION_ID",
"botId": "BOT_ID",
"userId": "USER_ID",
"status": "active"
}
}
Webhook event conversation.start
When this resource is executed, Jelou will emit the conversation.start event to the webhook configured in the integration. The payload varies depending on the fields sent in the request.
- Basic payload
- With assignment and metadata
{
"event": "conversation.start",
"timestamp": 1776133797422,
"field": "conversation",
"object": "conversation_event",
"event_type": "start",
"project_id": "PROJECT_ID",
"room_id": "ROOM_ID",
"contact": {
"id": "USER_ID",
"name": "USER_NAME"
},
"conversation": {
"id": "CONVERSATION_ID"
},
"bot": {
"id": "BOT_ID",
"name": "BOT_NAME"
},
"value": {}
}
{
"event": "conversation.start",
"timestamp": 1776134145523,
"field": "conversation",
"object": "conversation_event",
"event_type": "start",
"project_id": "PROJECT_ID",
"room_id": "ROOM_ID",
"contact": {
"id": "USER_ID",
"name": "USER_NAME"
},
"conversation": {
"id": "CONVERSATION_ID",
"assignment": {
"type": "queue",
"target": "SUPPORT"
}
},
"bot": {
"id": "BOT_ID",
"name": "BOT_NAME"
},
"value": {
"initial_message": "Hello, good morning",
"metadata": {
"ticketId": "T-12345"
}
}
}
Payload fields
| Field | Type | Description |
|---|---|---|
event | string | Event name: conversation.start |
timestamp | number | Unix timestamp in milliseconds at the time of the event. |
project_id | string | Jelou project identifier. |
room_id | string | Conversation room identifier. |
contact.id | string | End user identifier. |
contact.name | string | End user name. |
conversation.id | string | Unique identifier of the started conversation. |
conversation.assignment.type | string | Assignment type: queue or direct. |
conversation.assignment.target | string | Queue name or target agent ID. |
bot.id | string | Assigned bot identifier. |
bot.name | string | Assigned bot name. |
value.initial_message | string | Initial message sent when the conversation started (optional). |
value.metadata | object | Additional conversation metadata (optional). |
Authorizations
Basic authentication using Base64 encoded clientId:clientSecret
Path Parameters
Unique identifier of the Jelou project
Body
application/json
Response
Conversation started successfully
Was this page helpful?
⌘I