Broker

Further described at the Conversation API section, those are the methods used on conversation.

The broker API is responsible for managing the conversations performed by your users. While it is listed here, we encourage you to visit it's specific page for a complete orientation of how to use it.

Conversation Methods

Start a new conversation.

post

Path parameters

orgUUIDstringRequired

envUUIDstringRequired

botUUIDstringRequired

channelUUIDstringRequired

Query parameters

testbooleanOptional

It is the flag if the conversation is one test

Default: false

Header parameters

API-KEYstringRequired

OSstringRequired

OS-VERSIONstringOptional

BROWSERstringOptional

BROWSER-VERSIONstringOptional

USER-REFstringRequired

BUSINESS-KEYstringOptional

LOCALEstringRequired

OriginstringOptional

The origin of the request

Default: ""

x-request-idstringOptional

x-b3-traceidstringOptional

x-b3-spanidstringOptional

x-b3-parentspanidstringOptional

x-b3-sampledstringOptional

x-b3-flagsstringOptional

x-ot-span-contextstringOptional

Body

textstringOptional

codestringOptional

intentstringOptional

confidencenumber · doubleOptional

inputTextbooleanOptional

toApplyMultilanguagebooleanOptional

userInputstringOptional

Responses

200

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

429

Too many requests

application/json

460

Error while communicating with external webhooks

application/json

461

Misconfigured flows or bots

application/json

462

Error while communicating with nlp

application/json

463

Authentication/authorization error in nlp

application/json

500

Internal Server Error

application/json

post

POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations HTTP/1.1
Host: 
API-KEY: text
OS: text
USER-REF: text
LOCALE: text
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "text": "text",
  "code": "text",
  "intent": "text",
  "confidence": 1,
  "context": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "entities": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "advancedOptions": {
    "multilanguage": {
      "translateInput": true
    }
  },
  "inputText": true,
  "toApplyMultilanguage": true,
  "userInput": "text"
}

{
  "text": "text",
  "sessionCode": "text",
  "userInteractionUUID": "text",
  "userInput": {
    "type": "text",
    "callToAction": "text",
    "pattern": "text"
  },
  "nlpResponse": {
    "type": "QUESTION",
    "name": "text",
    "score": 1,
    "entities": [
      {
        "name": "text",
        "value": "text",
        "originalValue": "text",
        "position": {
          "start": 1,
          "end": 1
        }
      }
    ]
  },
  "answers": [
    {
      "content": {},
      "technicalText": {},
      "buttons": [
        {
          "name": "text",
          "value": "text",
          "type": "text",
          "action": "text"
        }
      ],
      "quickReply": [
        {
          "name": "text",
          "value": "text"
        }
      ],
      "description": "text",
      "type": "text",
      "interactionId": "text",
      "evaluable": true,
      "masked": true
    }
  ],
  "context": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "contextReadOnly": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}

Continues a conversation with the specified session code.

post

Path parameters

sessionCodestringRequired

orgUUIDstringRequired

envUUIDstringRequired

botUUIDstringRequired

channelUUIDstringRequired

Query parameters

testbooleanOptional

It is the flag if the conversation is one test

Default: false

Header parameters

API-KEYstringRequired

OSstringRequired

OS-VERSIONstringOptional

BROWSERstringOptional

BROWSER-VERSIONstringOptional

USER-REFstringRequired

BUSINESS-KEYstringOptional

LOCALEstringRequired

OriginstringOptional

The origin of the request

Default: ""

x-request-idstringOptional

x-b3-traceidstringOptional

x-b3-spanidstringOptional

x-b3-parentspanidstringOptional

x-b3-sampledstringOptional

x-b3-flagsstringOptional

x-ot-span-contextstringOptional

Body

textstringOptional

codestringOptional

intentstringOptional

confidencenumber · doubleOptional

inputTextbooleanOptional

toApplyMultilanguagebooleanOptional

userInputstringOptional

Responses

200

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

429

Too many requests

application/json

460

Error while communicating with external webhooks

application/json

461

Misconfigured flows or bots

application/json

462

Error while communicating with nlp

application/json

463

Authentication/authorization error in nlp

application/json

500

Internal Server Error

application/json

post

POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations/{sessionCode} HTTP/1.1
Host: 
API-KEY: text
OS: text
USER-REF: text
LOCALE: text
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "text": "text",
  "code": "text",
  "intent": "text",
  "confidence": 1,
  "context": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "entities": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "advancedOptions": {
    "multilanguage": {
      "translateInput": true
    }
  },
  "inputText": true,
  "toApplyMultilanguage": true,
  "userInput": "text"
}

{
  "text": "text",
  "sessionCode": "text",
  "userInteractionUUID": "text",
  "userInput": {
    "type": "text",
    "callToAction": "text",
    "pattern": "text"
  },
  "nlpResponse": {
    "type": "QUESTION",
    "name": "text",
    "score": 1,
    "entities": [
      {
        "name": "text",
        "value": "text",
        "originalValue": "text",
        "position": {
          "start": 1,
          "end": 1
        }
      }
    ]
  },
  "answers": [
    {
      "content": {},
      "technicalText": {},
      "buttons": [
        {
          "name": "text",
          "value": "text",
          "type": "text",
          "action": "text"
        }
      ],
      "quickReply": [
        {
          "name": "text",
          "value": "text"
        }
      ],
      "description": "text",
      "type": "text",
      "interactionId": "text",
      "evaluable": true,
      "masked": true
    }
  ],
  "context": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "contextReadOnly": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}

Saves a satisfaction survey in an existing conversation.

post

Path parameters

sessionCodestringRequired

orgUUIDstringRequired

envUUIDstringRequired

botUUIDstringRequired

Header parameters

API-KEYstringRequired

LOCALEstringRequired

x-request-idstringOptional

x-b3-traceidstringOptional

x-b3-spanidstringOptional

x-b3-parentspanidstringOptional

x-b3-sampledstringOptional

x-b3-flagsstringOptional

x-ot-span-contextstringOptional

Body

evaluationinteger · int32Optional

answeredbooleanOptional

userCommentsstringOptional

expireSessionbooleanOptional

Responses

200

application/json

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

application/json

post

POST /org/{orgUUID}/env/{envUUID}/bot/{botUUID}/conversations/{sessionCode}/satisfactions HTTP/1.1
Host: 
API-KEY: text
LOCALE: text
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "evaluation": 1,
  "answered": true,
  "userComments": "text",
  "expireSession": true
}

{
  "text": "text",
  "sessionCode": "text",
  "userInteractionUUID": "text",
  "userInput": {
    "type": "text",
    "callToAction": "text",
    "pattern": "text"
  },
  "nlpResponse": {
    "type": "QUESTION",
    "name": "text",
    "score": 1,
    "entities": [
      {
        "name": "text",
        "value": "text",
        "originalValue": "text",
        "position": {
          "start": 1,
          "end": 1
        }
      }
    ]
  },
  "answers": [
    {
      "content": {},
      "technicalText": {},
      "buttons": [
        {
          "name": "text",
          "value": "text",
          "type": "text",
          "action": "text"
        }
      ],
      "quickReply": [
        {
          "name": "text",
          "value": "text"
        }
      ],
      "description": "text",
      "type": "text",
      "interactionId": "text",
      "evaluable": true,
      "masked": true
    }
  ],
  "context": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "contextReadOnly": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}

API Key

Retrieves the API key for the specified organization and environment.

get

Path parameters

orgUUIDstringRequired

A valid organization UUID

envUUIDstringRequired

A valid environment UUID

Responses

200

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

408

Request Timeout

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

get

GET /org/{orgUUID}/env/{envUUID}/api-key HTTP/1.1
Host: 
Accept: */*

{
  "apiKey": "text"
}

Likable

Save user's evaluation

post

Path parameters

orgUUIDstringRequired

A valid organization UUID

envUUIDstringRequired

A valid environment UUID

Query parameters

requesterIdstringRequired

Query parameter for the requester ID

Header parameters

API-KEYstringRequired

The API key from the request header for authorization

Body

Contain customer satisfaction data

evaluationbooleanOptional

Indicates whether the interaction should be evaluated.

interactionIdstringOptional

Unique identifier for the interaction.

Responses

200

*/*

Responsestring

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

408

Request Timeout

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

post

POST /org/{orgUUID}/env/{envUUID}/likable?requesterId=text HTTP/1.1
Host: 
API-KEY: text
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "evaluation": true,
  "interactionId": "text"
}

text

History

Get conversation history

get

Path parameters

businessKeystringRequired

The business key to retrieve history

orgUUIDstringRequired

A valid organization UUID

envUUIDstringRequired

A valid environment UUID

Responses

200

*/*

400

Bad Request

*/*

401

Unauthorized

*/*

403

Forbidden

*/*

404

Not Found

*/*

408

Request Timeout

*/*

409

Conflict

*/*

422

Unprocessable Entity

*/*

500

Internal Server Error

*/*

get

GET /org/{orgUUID}/env/{envUUID}/history/{businessKey} HTTP/1.1
Host: 
Accept: */*

[
  {
    "session": {
      "sessionCode": "text",
      "createDate": "2025-09-03T10:19:34.236Z",
      "expireDate": "2025-09-03T10:19:34.236Z",
      "businessKey": "text",
      "sessionType": "CREATED",
      "botId": "text",
      "channelId": "text",
      "operatingSystem": "text",
      "operatingSystemVersion": "text",
      "browser": "text",
      "browserVersion": "text",
      "userRef": "text",
      "locale": "text",
      "test": true
    },
    "userInteractions": [
      {
        "id": 1,
        "createDate": "2025-09-03T10:19:34.236Z",
        "sessionCode": "text",
        "userSent": true,
        "answerUuid": "text",
        "text": "text",
        "intent": "text",
        "confidence": 1,
        "entities": "text",
        "userSentId": "text",
        "evaluation": true,
        "uuid": "text"
      }
    ]
  }
]

PreviousBot NextChannel

Last updated 13 days ago

Was this helpful?