Start conversation

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": {}
}

POST

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 bot that will handle the conversation, the target user, an initial message, and assignment data for queues or agents. Upon execution, Jelou emits the conversation.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 bot 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, or team.
target — Queue name or target agent identifier.

Authentication

All requests must include the x-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 the SUPPORT 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	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

x-api-key

string

header

required

API key del proyecto de Jelou

Path Parameters

projectId

string

required

Unique identifier of the Jelou project

Body

application/json

botId

string

required

userId

string

required

initialMessage

string

metadata

object

assignment

object

Show child attributes

Response

Conversation started successfully

Regenerate signing secret

Close conversation

⌘I

API reference

Send Messages

Campaigns

Conversations

Metrics

Users

Resources

Widget

Datum

External Support Panel

Memory Management

Description

Endpoint

Path parameters

Body parameters

Authentication

Request example

Responses

Response example

Webhook event `conversation.start`

Payload fields

Authorizations

Path Parameters

Body

Response

​Description

​Endpoint

​Path parameters

​Body parameters

​Authentication

​Request example

​Responses

​Response example

​Webhook event conversation.start

​Payload fields

Authorizations

Path Parameters

Body

Response

Description

Endpoint

Path parameters

Body parameters

Authentication

Request example

Responses

Response example

Webhook event `conversation.start`

Payload fields