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

testboolean · default: falseoptional

It is the flag if the conversation is one test

Header parameters

API-KEYstringrequired

OSstringrequired

OS-VERSIONstringoptional

BROWSERstringoptional

BROWSER-VERSIONstringoptional

USER-REFstringrequired

BUSINESS-KEYstringoptional

LOCALEstringrequired

Originstring · default: ""optional

The origin of the request

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

contextobjectoptional

entitiesobjectoptional

advancedOptionsobjectoptional

Represents an AdvancedOptionsDTO object that contains advanced options for a conversation

inputTextbooleanoptional

toApplyMultilanguagebooleanoptional

userInputstringoptional

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

application/json

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations' \
  --header 'API-KEY: text' \
  --header 'OS: text' \
  --header 'USER-REF: text' \
  --header 'LOCALE: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "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"
  }'

200

400

401

403

404

409

422

429

460

461

462

463

500

200

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

Ok

Continues a conversation with the specified session code.

post

Path parameters

sessionCodestringrequired

orgUUIDstringrequired

envUUIDstringrequired

botUUIDstringrequired

channelUUIDstringrequired

Query parameters

testboolean · default: falseoptional

It is the flag if the conversation is one test

Header parameters

API-KEYstringrequired

OSstringrequired

OS-VERSIONstringoptional

BROWSERstringoptional

BROWSER-VERSIONstringoptional

USER-REFstringrequired

BUSINESS-KEYstringoptional

LOCALEstringrequired

Originstring · default: ""optional

The origin of the request

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

contextobjectoptional

entitiesobjectoptional

advancedOptionsobjectoptional

Represents an AdvancedOptionsDTO object that contains advanced options for a conversation

inputTextbooleanoptional

toApplyMultilanguagebooleanoptional

userInputstringoptional

Responses

application/json

*/*

*/*

*/*

*/*

*/*

*/*

application/json

application/json

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/channel/{channelUUID}/v1/conversations/{sessionCode}' \
  --header 'API-KEY: text' \
  --header 'OS: text' \
  --header 'USER-REF: text' \
  --header 'LOCALE: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "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"
  }'

200

400

401

403

404

409

422

429

460

461

462

463

500

200

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

Ok

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

application/json

*/*

*/*

*/*

*/*

*/*

*/*

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/org/{orgUUID}/env/{envUUID}/bot/{botUUID}/conversations/{sessionCode}/satisfactions' \
  --header 'API-KEY: text' \
  --header 'LOCALE: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "evaluation": 1,
    "answered": true,
    "userComments": "text",
    "expireSession": true
  }'

200

400

401

403

404

409

422

500

200

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

Ok

API Key

get

Path parameters

orgUUIDstringrequired

envUUIDstringrequired

Responses

*/*

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/api-key'

200

400

401

403

404

409

422

500

200

{
  "apiKey": "text"
}

OK

Likable

post

Path parameters

orgUUIDstringrequired

envUUIDstringrequired

Query parameters

requesterIdstringrequired

Header parameters

API-KEYstringrequired

Body

evaluationbooleanoptional

interactionIdstringoptional

Responses

*/*

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/org/{orgUUID}/env/{envUUID}/likable?requesterId=text' \
  --header 'API-KEY: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "evaluation": true,
    "interactionId": "text"
  }'

200

400

401

403

404

409

422

500

200

text

OK

History

get

Path parameters

businessKeystringrequired

orgUUIDstringrequired

envUUIDstringrequired

Responses

*/*

*/*

*/*

*/*

*/*

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/org/{orgUUID}/env/{envUUID}/history/{businessKey}'

200

400

401

403

404

409

422

500

200

[
  {
    "session": {
      "sessionCode": "text",
      "createDate": "2025-03-28T09:59:51.664Z",
      "expireDate": "2025-03-28T09:59:51.664Z",
      "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-03-28T09:59:51.664Z",
        "sessionCode": "text",
        "userSent": true,
        "answerUuid": "text",
        "text": "text",
        "intent": "text",
        "confidence": 1,
        "entities": "text",
        "userSentId": "text",
        "evaluation": true,
        "uuid": "text"
      }
    ]
  }
]

OK