Iniciar conversa - Jelou AI Docs

Start Conversation

curl --request POST \
  --url https://gateway.jelou.ai/jelouapi/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>"
  }
}
'

{
  "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 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --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": {}
}

Descrição

Inicia uma nova conversa com um usuário final no painel de atendimento externo. Permite especificar o bot que atenderá a conversa, o usuário destinatário, uma mensagem inicial e dados de atribuição a filas ou agentes. Ao ser executado, o Jelou emite o evento conversation.start para o webhook configurado na integração.

Endpoint

POST https://gateway.jelou.ai/jelouapi/v1/external-support/{projectId}/conversations/start

Parâmetros de rota

projectId

string

obrigatório

Identificador único do projeto Jelou a partir do qual a conversa é iniciada.

Parâmetros do corpo

botId

string

obrigatório

Identificador do bot do Jelou que gerenciará a conversa.

userId

string

obrigatório

Identificador do usuário final com quem a conversa será iniciada.

initialMessage

string

Mensagem inicial que será enviada ao iniciar a conversa. Se omitida, a conversa inicia sem mensagem prévia.

metadata

object

Dados adicionais associados à conversa. Podem incluir identificadores externos, números de ticket ou outro contexto relevante para o seu sistema.Exemplo: { "ticketId": "T-12345" }

assignment

object

Configuração de atribuição da conversa a uma fila ou agente específico.

type — Tipo de atribuição: queue (fila), operator (operador) ou team (equipe).
target — Nome da fila ou identificador do agente destino.

Autenticação

Todas as requisições devem incluir o cabeçalho x-api-key com a API key do projeto Jelou.

x-api-key: API_KEY

Exemplo de requisição

O exemplo a seguir inicia uma conversa com atribuição à fila SUPORTE e inclui metadata de ticket:

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": "Olá, preciso de ajuda",
    "metadata": { "ticketId": "T-12345" },
    "assignment": { "type": "queue", "target": "SUPORTE" }
  }'

Respostas

Código	Status	Descrição
200	OK	Conversa iniciada com sucesso.
401	Unauthorized	Credenciais de autenticação inválidas ou ausentes.
404	Not Found	Bot ou usuário não encontrado.
422	Bad Request	Campos obrigatórios ausentes ou formato inválido.
500	Internal Server Error	Erro interno do servidor.

Exemplo de resposta

{
  "message": [
    "Conversation started successfully"
  ],
  "statusMessage": "success",
  "status": 1,
  "data": {
    "conversationId": "CONVERSATION_ID",
    "botId": "BOT_ID",
    "userId": "USER_ID",
    "status": "active"
  }
}

Evento webhook `conversation.start`

Ao executar este recurso, o Jelou emitirá o evento conversation.start ao webhook configurado na integração. O payload varia conforme os campos enviados na requisição.

Payload básico
Com atribuição e 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": "SUPORTE"
    }
  },
  "bot": {
    "id": "BOT_ID",
    "name": "BOT_NAME"
  },
  "value": {
    "initial_message": "Olá, bom dia",
    "metadata": {
      "ticketId": "T-12345"
    }
  }
}

Campos do payload

Campo	Tipo	Descrição
`event`	string	Nome do evento: `conversation.start`
`timestamp`	number	Marca de tempo Unix em milissegundos do momento do evento.
`project_id`	string	Identificador do projeto Jelou.
`room_id`	string	Identificador da sala de conversa.
`contact.id`	string	Identificador do usuário final.
`contact.name`	string	Nome do usuário final.
`conversation.id`	string	Identificador único da conversa iniciada.
`conversation.assignment.type`	string	Tipo de atribuição: `queue` ou `direct`.
`conversation.assignment.target`	string	Nome da fila ou ID do agente destino.
`bot.id`	string	Identificador do bot atribuído.
`bot.name`	string	Nome do bot atribuído.
`value.initial_message`	string	Mensagem inicial enviada ao iniciar a conversa (opcional).
`value.metadata`	object	Metadata adicional da conversa (opcional).

Autorizações

x-api-key

string

header

obrigatório

API key del proyecto de Jelou

Parâmetros de caminho

projectId

string

obrigatório

Unique identifier of the Jelou project

Corpo

application/json

botId

string

obrigatório

userId

string

obrigatório

initialMessage

string

metadata

object

assignment

object

Show child attributes

Resposta

Conversation started successfully

Regenerar signing secret

Encerrar conversa

⌘I

​Descrição

​Endpoint

​Parâmetros de rota

​Parâmetros do corpo

​Autenticação

​Exemplo de requisição

​Respostas

​Exemplo de resposta

​Evento webhook conversation.start

​Campos do payload

Autorizações

Parâmetros de caminho

Corpo

Resposta

Descrição

Endpoint

Parâmetros de rota

Parâmetros do corpo

Autenticação

Exemplo de requisição

Respostas

Exemplo de resposta

Evento webhook `conversation.start`

Campos do payload