Textchat V2 API

API Specification of the Parloa TextchatV2 API

The Parloa Textchat V2 API provides a simple request-response mechanism to integrate a Parloa text chat bot into your application or chat system. Utilize a single endpoint for sending TextchatV2Request events and receiving TextchatV2Response, facilitating easy conversation management.

Conversation Protocol

1. Initiate a Conversation: Send a TextchatV2LaunchEvent to begin, receiving a welcome message in response.

2. Continue Conversing: Utilize TextchatV2MessageEvent for user responses. The conversation remains active until the bot sets endConversation to true or a TextchatV2QuitEvent is sent.

Authentication

To authenticate against the textchat bot, invoke the dialoghook webhook with a Bearer token containing the apiToken generated during the textchat bot's release creation.

Authorization: Bearer <apiToken>

Prerequisites

• Register on the Parloa developer platform to get an API key.

• Ensure your server supports HTTP POST requests.

• Be familiar with JSON payloads, as this API requires them.

Endpoint

• URL: https://app.parloa.com/dialoghook?dialog=<releaseId>&platform=textchatV2

• Method: POST

Request

Query Parameters

• dialog (Required, string) – The releaseId of your Textchat V2 release.

• platform (Required, string) – For this API, you must set the platform to "textchatV2".

Body Parameters

• apiVersion (Required) – The version of the API you are using.

• event (Required, TextchatV2Event) – The type of event. This can be one of the following – Define the event type. This could be one of the following:

  • TextchatV2LaunchEvent: To indicate that a user wants to start a new chat.

  • TextchatV2MessageEvent: To signal that a user has sent a new message.

  • TextchatV2QuitEvent: To notify that a user has left the chat.

• requesterId (Required, string) – An identifier for Parloa to recognize a user. Typically, this would be something like a user ID.

• sessionId (Required, string) – The conversationId of the chat widget. Parloa uses this to maintain the state of the chat between a user and a Parloa bot.

• context (Optional, Array with a maximum of 100 items) – Additional context information to pass to the Parloa bot.

  • TextchatV2ContextItem

    • key (Required, string) – The identifier for a context field that the bot can access.

    • value (Required) – The actual context item value.

Request Headers

• Authorization – Your API key.

• accept - application/json.

• Content-Type - application/json.

Response

When you send a request to TextchatV2, the service returns a JSON-formatted response that you can parse to extract necessary information.

Response Codes

• 200 OK: Event successfully sent.

• 400 Bad Request: Invalid or incomplete request.

• 401 Unauthorized: Incorrect or missing API key.

• 404 Not Found: Specified chat session does not exist.

Making a POST Request

To initiate any interaction with Parloa's chatbot, send a POST request to https://app.parloa.com/dialoghook?dialog=<releaseId>&platform=textchatV2. For every request, you must do the following:

1. Substitute YOUR_API_KEY with the API key you have from the Parloa developer platform.

2. Insert relevant identifiers for <user-id> and <session-id>.

3. Replace <release_id> in the URL with your Textchat V2 release-specific ID.

Types of Requests

Starting a Conversation

To initiate a conversation, use the launch event type, representing TextchatV2LaunchEvent.

curl -X POST \
  -H Authorization: Bearer YOUR_API_KEY \
  -H Content-Type: application/json \
  -d '{
    "apiVersion": "chat/v1",
    "requesterId": "<user-id>",
    "sessionId": "<session-id>",
    "event": {
      "type": "launch"
    }
  }' \
  https://app.parloa.com/dialoghook?dialog=<release_id>&platform=textchatV2

Sending a Message to the Bot

The message event type is employed for ongoing conversations and represents TextchatV2MessageEvent.

curl -X POST \
  -H Authorization: Bearer YOUR_API_KEY \
  -H Content-Type: application/json \
  -d '{
    "apiVersion": "chat/v1",
    "requesterId": "<user-id>",
    "sessionId": "<session-id>",
    "event": {
      "type": "message",
      "text": "Hello textchat!"
    }
  }' \
  https://app.parloa.com/dialoghook?dialog=<release_id>&platform=textchatV2

Sending a Message with Context to the Bot

In a continuous conversation, you can send additional context.

curl -X POST \
  -H Authorization: Bearer YOUR_API_KEY \
  -H Content-Type: application/json \
  -d '{
    "apiVersion": "chat/v1",
    "requesterId": "<user-id>",
    "sessionId": "<session-id>",
    "context": [
      {
        "key": "name",
        "value": "Max"
      },
      {
        "key": "age",
        "value": 20
      }
    ],
    "event": {
      "type": "message",
      "text": "Hello textchat!"
    }
  }' \
  https://app.parloa.com/dialoghook?dialog=<release_id>&platform=textchatV2

Ending the Conversation

The quit event type signals to the bot that you wish to end the conversation.

curl -X POST \
  -H Authorization: Bearer YOUR_API_KEY \
  -H Content-Type: application/json \
  -d '{
    "apiVersion": "chat/v1",
    "requesterId": "<user-id>",
    "sessionId": "<session-id>",
    "event": {
      "type": "quit"
    }
  }' \
  https://app.parloa.com/dialoghook?dialog=<release_id>&platform=textchatV2

Response Parameters

• apiVersion (Required, string) – The version of the API being used.

• conversationId (Optional, string) – The ID of the current conversation.

• endConversation (Required, boolean) – This field will be set to true if the conversation is intended to terminate with this response.

• releaseId (Required, string) – The identifier for the specific release of the bot that generated this response.

• requesterId (Required, string) – This is the same identifier you initially sent in your TextchatV2Request under requesterId. It's used to recognize participants in the conversation.

• responseElements (Required, array) – This is where you'll find all the elements that make up the bot's response. Each element is an object that could contain various types of data or instructions.

  • TextchatV2ResponseItem: This would contain additional details specific to each response item.

• sessionId (Required, string) – Just like requesterId, this is an echo back of the sessionId you sent in your TextchatV2Request. Parloa uses this to keep track of conversation states between a user and a Parloa bot.

For a detailed schema of the TextChat V2 API, click here.