Start Conversation
curl --request POST \
--url https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
'import requests
url = "https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start"
payload = {
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
botId: '<string>',
userId: '<string>',
initialMessage: '<string>',
metadata: {},
assignment: {type: '<string>', target: '<string>'}
})
};
fetch('https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'botId' => '<string>',
'userId' => '<string>',
'initialMessage' => '<string>',
'metadata' => [
],
'assignment' => [
'type' => '<string>',
'target' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start"
payload := strings.NewReader("{\n \"botId\": \"<string>\",\n \"userId\": \"<string>\",\n \"initialMessage\": \"<string>\",\n \"metadata\": {},\n \"assignment\": {\n \"type\": \"<string>\",\n \"target\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"botId\": \"<string>\",\n \"userId\": \"<string>\",\n \"initialMessage\": \"<string>\",\n \"metadata\": {},\n \"assignment\": {\n \"type\": \"<string>\",\n \"target\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"botId\": \"<string>\",\n \"userId\": \"<string>\",\n \"initialMessage\": \"<string>\",\n \"metadata\": {},\n \"assignment\": {\n \"type\": \"<string>\",\n \"target\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}{
"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/platform/v1/external-support/{projectId}/conversations/start \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
'import requests
url = "https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start"
payload = {
"botId": "<string>",
"userId": "<string>",
"initialMessage": "<string>",
"metadata": {},
"assignment": {
"type": "<string>",
"target": "<string>"
}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
botId: '<string>',
userId: '<string>',
initialMessage: '<string>',
metadata: {},
assignment: {type: '<string>', target: '<string>'}
})
};
fetch('https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'botId' => '<string>',
'userId' => '<string>',
'initialMessage' => '<string>',
'metadata' => [
],
'assignment' => [
'type' => '<string>',
'target' => '<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start"
payload := strings.NewReader("{\n \"botId\": \"<string>\",\n \"userId\": \"<string>\",\n \"initialMessage\": \"<string>\",\n \"metadata\": {},\n \"assignment\": {\n \"type\": \"<string>\",\n \"target\": \"<string>\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"botId\": \"<string>\",\n \"userId\": \"<string>\",\n \"initialMessage\": \"<string>\",\n \"metadata\": {},\n \"assignment\": {\n \"type\": \"<string>\",\n \"target\": \"<string>\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://gateway.jelou.ai/platform/v1/external-support/{projectId}/conversations/start")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"botId\": \"<string>\",\n \"userId\": \"<string>\",\n \"initialMessage\": \"<string>\",\n \"metadata\": {},\n \"assignment\": {\n \"type\": \"<string>\",\n \"target\": \"<string>\"\n }\n}"
response = http.request(request)
puts response.read_body{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}{
"message": "<string>",
"statusMessage": "<string>",
"status": 123,
"error": {
"code": "<string>",
"key": "<string>",
"description": "<string>",
"developerMessages": {},
"clientMessages": {}
},
"validationError": {}
}Description
Starts a new conversation with an end user in the external support panel. Allows specifying the channel 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/platform/v1/external-support/{projectId}/conversations/start
Path parameters
string
required
Unique identifier of the Jelou project from which the conversation is started.
Body parameters
string
required
Identifier of the Jelou channel that will manage the conversation.
string
required
Identifier of the end user with whom the conversation will be started.
string
Initial message to be sent when the conversation starts. If omitted, the conversation starts without a prior message.
object
Additional data associated with the conversation. Can include external identifiers, ticket numbers, or other context relevant to your system.Example:
{ "ticketId": "T-12345" }object
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/platform/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 | Channel 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 channel identifier. |
bot.name | string | Assigned channel name. |
value.initial_message | string | Initial message sent when the conversation started (optional). |
value.metadata | object | Additional conversation metadata (optional). |
Authorizations
API key del proyecto de Jelou
Path Parameters
Unique identifier of the Jelou project
Body
application/json
Response
Conversation started successfully
Was this page helpful?
⌘I