Working with Puzzel Chat API

Puzzel Chat API is a tool designed for integrating communication into your applications. It supports a range of features including message handling, connection management, and conversation tracking. Additionally, it offers real-time data processing, allocation, queues and the use of Puzzel time module. With clear endpoints, the API is built to allow customers to create integrations to the chat channel in Puzzel Contact centre, allowing them to implement and manage chat functionalities inside their own application areas.

To see and interact with the API visit this Swagger page where it is possible to read the API, and the Swagger also includes a example client with illustrative code samples in different languages.

The Swagger can be found here: https://app-cdn.puzzel.com/public/chat-api-swagger/index.html

Using the sample test client

In the swagger link above Puzzel provide a reference implementation and a working sample test client that can be used to kick start development efforts. To use this in your Puzzel Contact Center chat you will need to have your solution id and your visual queue id ready. See Puzzel help for Puzzel Contact Center for where to find this information.

Creating a session

To communicate with the API you need to use a token. You obtain a token from the endpoint “connect/token” and you can see an example of this using the link above. A token is the holder of the session. Tokens follow an OICD standard and the response also contains a refresh token to refresh you token before expiry. The “expires_in” property returned from the connect/token call will give the time untill the token need to be refreshed. See OICD standard for details.

Requesting an agent

The chat client can check for opening hours and using the /api/queue/info/{id} call if needed

After this the client can call the method /api/conversation/{id}/route/ to ask the contact center to find and assign an agent. The api expects partners to set their own chat conversation id.

After the route command it is possible to call the /api/allocation/requestStatus/{id} to get status on finding and agent for the conversation

Polling for messages

New messages should be polled at interval. For example every second and the endpoint /api/conversation is used for this. See Swagger for details.

Metadata Events API

The POST /api/metadata/{id} endpoint broadcasts events to participants within a conversation, where {id} is the unique conversation identifier. This allows real-time updates about participants' actions and status changes.

Standard Events

While the system supports arbitrary event names, the primary agent application listens for and emits the following standard events:

• participantJoinEvent: Signals that a new participant has joined the conversation.
• participantLeaveEvent: Signals that a participant has left the conversation.
• typingEvent: Signals that a participant is currently typing.

Request Body

The request body must be a JSON object with the following structure:

Example Payload:

{
    "senderName": "Alice",
    "event": "typingEvent"
}

{ "sender": "Alice", "event": "typingEvent" }

Polling for Metadata Events

To retrieve events from other participants, such as an agent, you can poll the GET /api/metadata/{id} endpoint.

This endpoint returns a list of all metadata events that have occurred within the conversation identified by {id}.

Interpreting Agent Events

When polling, the following events originating from an agent have specific meanings:

• participantJoinEvent: Indicates the agent has successfully joined and accepted the conversation.
• participantLeaveEvent: Indicates the agent has left or ended the conversation.
• typingEvent: Indicates the agent is actively typing a message.

Response Body

The response contains a JSON object with a senderName and event field.

Example Response:

This example shows that an agent named "AgentBob" is typing.

  {
    "senderName": "AgentBob",
    "event": "typingEvent"
  }