Start conversation - Jelou AI Docs

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

POST

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

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/jelouapi/v1/external-support/{projectId}/conversations/start

Path parameters

projectId

string

required

Unique identifier of the Jelou project from which the conversation is started.

Body parameters

botId

string

required

Identifier of the Jelou bot that will manage the conversation.

userId

string

required

Identifier of the end user with whom the conversation will be started.

initialMessage

string

Initial message to be sent when the conversation starts. If omitted, the conversation starts without a prior message.

metadata

object

Additional data associated with the conversation. Can include external identifiers, ticket numbers, or other context relevant to your system.Example: { "ticketId": "T-12345" }

assignment

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/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

Authorization

string

header

required

Basic authentication using Base64 encoded clientId:clientSecret

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

Documentation Index

​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