> ## 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.

# Start conversation

> Start a new conversation with an end user

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

<ParamField path="projectId" type="string" required>
  Unique identifier of the Jelou project from which the conversation is started.
</ParamField>

## Body parameters

<ParamField body="botId" type="string" required>
  Identifier of the Jelou bot that will manage the conversation.
</ParamField>

<ParamField body="userId" type="string" required>
  Identifier of the end user with whom the conversation will be started.
</ParamField>

<ParamField body="initialMessage" type="string">
  Initial message to be sent when the conversation starts. If omitted, the conversation starts without a prior message.
</ParamField>

<ParamField body="metadata" type="object">
  Additional data associated with the conversation. Can include external identifiers, ticket numbers, or other context relevant to your system.

  Example: `{ "ticketId": "T-12345" }`
</ParamField>

<ParamField body="assignment" type="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.
</ParamField>

## 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:

```bash cURL theme={null}
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

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="Basic payload">
    ```json theme={null}
    {
      "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": {}
    }
    ```
  </Tab>

  <Tab title="With assignment and metadata">
    ```json theme={null}
    {
      "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"
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 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).                   |


## OpenAPI

````yaml POST /v1/external-support/{projectId}/conversations/start
openapi: 3.1.0
info:
  title: Jelou API
  description: >-
    API for the Jelou platform. Send messages, manage campaigns, handle
    conversations, users, databases, and widgets.
  version: 1.0.0
servers:
  - url: https://api.jelou.ai
    description: Production server
security:
  - basicAuth: []
tags:
  - name: Messages
    description: Send messages to users
  - name: Campaigns
    description: HSM campaigns and templates
  - name: Conversations
    description: Chat history and metrics
  - name: Users
    description: User state and cache management
  - name: Resources
    description: Media resource management
  - name: Datum
    description: Database CRUD operations
  - name: Widget
    description: Widget and room management
  - name: PMA Custom
    description: External support panel integration
paths:
  /v1/external-support/{projectId}/conversations/start:
    servers:
      - url: https://gateway.jelou.ai/platform
        description: External Support Panel API
    post:
      tags:
        - External Support Panel
      summary: Start Conversation
      description: Start a new conversation with an end user in the external support panel.
      operationId: startExternalConversation
      parameters:
        - name: projectId
          in: path
          required: true
          description: Unique identifier of the Jelou project
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - botId
                - userId
              properties:
                botId:
                  type: string
                userId:
                  type: string
                initialMessage:
                  type: string
                metadata:
                  type: object
                assignment:
                  type: object
                  properties:
                    type:
                      type: string
                    target:
                      type: string
      responses:
        '200':
          description: Conversation started successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - apiKey: []
components:
  responses:
    Unauthorized:
      description: Unauthorized - Invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found - Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: Unprocessable entity - Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
        statusMessage:
          type: string
        status:
          type: integer
        error:
          type: object
          properties:
            code:
              type: string
            key:
              type: string
            description:
              type: string
            developerMessages:
              type: object
            clientMessages:
              type: object
        validationError:
          type: object
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using Base64 encoded clientId:clientSecret
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key del proyecto de Jelou

````