Textchat V2 API

API Specification of the Parloa TextchatV2 API

The Textchat V2 API allows you to integrate a chatbot into your application or chat system. With this API, you can manage conversations by sending requests and receiving responses from the bot. This guide explains how to use the API, even if you are new to technical concepts.

How It Works

The API works through a single URL (endpoint). You send data about the conversation, such as a user’s message or an event like starting or ending the chat, and the bot sends a response back. The bot uses this data to understand the user and keep track of the conversation.

Key Concepts

• Event: An action that happens during a conversation, such as starting, sending a message, or ending the chat.

• Session: A conversation instance between the user and the chatbot. Each session has a unique ID to keep track of the chat history.

• Bearer Token: A type of security key that ensures only authorized users can access the bot.

Getting Started

Before you begin, make sure the following prerequisites are met:

1. You have signed up on the and obtained your API key.

2. Your supports requests. (For example, you can use tools like curl or Postman).

3. You are familiar with JSON, a format used for sending and receiving data in this API.

Endpoint

To test specific parts of the chatbot via the API, such as verifying if an intent is recognized, send your requests to the following URL (referred to as the endpoint):

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

• Replace <releaseId> with the unique ID of your chatbot release.

• Always include the parameter platform=textchatV2.

---

Authentication

The API requires authentication to ensure only authorized users can send requests. Use the Bearer Token generated during your chatbot setup. Include it in the Authorization header of your request.

Example Format:

Authorization: Bearer YOUR_API_TOKEN

Conversation Protocol

1

Starting a Conversation

To initiate a conversation, send a TextchatV2LaunchEvent. This action creates a conversation context, and the bot responds with a welcome message.

2

Sending Messages

Messages are sent using the TextchatV2MessageEvent. This event enables you to communicate user input to the bot while maintaining the session context.

3

Ending a Conversation

To end a session, send a TextchatV2QuitEvent. This event signals the termination of the chat session and instructs Parloa RBA to:

1. Reset the conversation context.

2. Clear session-specific data, such as state and session-scoped variables.

3. Trigger the PARLOA.EndConversation event, ensuring accurate reporting.

If the TextchatV2QuitEvent is not sent, the session remains open indefinitely. Persistent data, such as storage variables with defined lifetimes, will not be cleared until explicitly reset. This behavior may impact reporting accuracy and session-specific analytics.

Key Notes on Session Handling

• Sessions are not time-scoped and persist until explicitly terminated.

• Persistent data (such as storage variables) remains across sessions unless manually reset.

• The method for detecting conversation termination differs by platform:

  • For TextchatV2, send the TextchatV2QuitEvent.

  • For Phone deployments, the system detects session termination through events such as a call hangup.

Request Parameters

Query Parameters

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

• platform (Required, string): Must be set to "textchatV2" for this API.

Body Parameters

• apiVersion (Required, string): Specifies the API version, such as "chat/v1".

• event (Required, object): The type of event you are sending. Options include:

  • TextchatV2LaunchEvent: Starts a new conversation.

  • TextchatV2MessageEvent: Sends a user message.

  • TextchatV2QuitEvent: Ends the conversation.

• requesterId (Required, string): A unique identifier for the user interacting with the bot. This could be a user ID from your system.

• sessionId (Required, string): A unique identifier for the conversation. Used to track the chat session between the user and the bot.

• context (Optional, array of TextchatV2ContextItem): Provides additional context for the chatbot to use during the conversation. Context items can include details like the user’s name, location, or preferences. Each item in the context array must follow the TextchatV2ContextItem format.

  • key (Required, string): A unique identifier for the context field. For example, "userName" could be used to pass the user's name to the bot.

  • value (Required, any): The actual value of the context field. For example, "Alice" might be the value for the "userName" key.

• callMeta (Optional, object): Metadata related to the conversation, particularly for tracking and debugging. Fields include:

  • callerId (string): A unique identifier for the user making the request, such as a phone number or user ID.

  • instanceId (string): A unique identifier for the instance handling the current session. This can be used for troubleshooting.

  • sessionId (string): The session ID associated with the chat. This ensures consistency across the conversation.

Request Headers

• Authorization (Required): Your API key in the format Bearer <apiToken>. This header is required for authentication.

• Accept (Required): The expected response format. Must be set to application/json.

• Content-Type (Required): The format of the request body. Must be set to application/json.

Making a POST Request

To communicate with Parloa's chatbot, send a POST request to the API endpoint. Every request must include:

• Use the API key from the Parloa developer platform for authentication.

• Replace <user-id>, <session-id>, and <release-id> with relevant values.

• Specify the type of action (for example, launch, message, or quit).

Starting a Conversation

This request starts a new conversation with the bot.

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 continue the conversation, send a message using the message event type.

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

You can include extra information (context) about the user when sending a message.

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": "userName",
        "value": "Alice"
      },
      {
        "key": "location",
        "value": "Berlin"
      }
    ],
    "event": {
      "type": "message",
      "text": "Hello chatbot!"
    }
  }' \
  https://app.parloa.com/dialoghook?dialog=<release-id>&platform=textchatV2

Ending a Conversation

To end the chat session, use the quit event.

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

The API returns a JSON-formatted response. Use the fields below to process the chatbot's response programmatically.

apiVersion (Required, string)

Specifies the version of the API used to generate the response. This field ensures the response adheres to the same API version specified in the request, maintaining consistency. Including the version provides clarity when debugging issues or validating compatibility between the client and server implementations.

conversationId (Optional, string)

A unique identifier for the ongoing conversation session. This value can be used to track or resume the conversation if needed. It is particularly useful for associating multiple requests or responses in analytics or debugging.

endConversation (Required, boolean)

Indicates whether the conversation is ending. When set to true, it signals that the bot considers the conversation complete and will not process additional input for this session unless explicitly restarted.

releaseId (Required, string)

Identifies the specific bot release that generated this response. This is critical for understanding which version of the bot handled the request, especially when multiple bot versions are deployed simultaneously.

requesterId (Required, string)

Echoes the requesterId value from the original request. This ensures continuity by linking the response to the user or entity initiating the request.

responseElements (Required, array)

An array of objects containing the bot's response. Each element represents a distinct part of the bot's reply, such as text messages, buttons, or other interactive elements. The exact structure depends on the bot's design and the response type.

sessionId (Required, string)

Echoes the session ID from the original request. This ensures that the client can associate the response with the correct ongoing conversation.

Error Handling

The API provides status codes to indicate success or failure:

Status Code	Description
200 OK	The request was successful, and the bot's response is included.
400 Bad Request	The request was invalid or missing required information.
401 Unauthorized	Your API key is missing or incorrect. Verify the Authorization header.
404 Not Found	The chatbot release or session could not be found. Check releaseId and sessionId.
500 Internal Server Error	An error occurred on the server. Try again later or contact support.