Chats API

Chats API enables you to manage chats and chat messages. This page presents some of the chat API endpoints available to users, as well as some chat specific webhooks.

Also see:

Get a Ticket's Timeline (User), which returns the list of all chat messages associated with a ticket.
Get the Sort Order Position of a Ticket Within a Saved Filter, which returns the position of a ticket within a saved filter, such as a chat queue. This is also useful to return the position of the user within the queue for a widget chat session.

Chat Unauthenticated User Header

When starting a chat for an authenticated user, first request an authorization token using the user's GUID. If you are starting the chat from a widget, and the user is not yet authenticated in Wix Answers, you can register the user using the user's email address. See Requesting a Specific User's Authorization Token from a Widget.

When starting a chat for an unauthenticated user, Wix Answers responds to the start request with a special header, x-answers-ags, to identify the user.

1
2
3
4
5
{
    ...
    x-answers-ags: 2dd5cd0dda1572e964cc2243693c1c08b41b24db80324d663da3f3c661fcd7339744217c450965141f54f3dedf8ffbf01d19c5ac20971993e3f2e55ff0354c08589ce5bea6130285b7d1ba4cc9fbd655702b96493c3947fb464f92b1c50e9713cd214a7d61b2d350411d4efe210ef571
    ...
}

You must send this header with any subsequent Chat API request (add user message, end chat, and so forth). For example:

1
2
3
4
5
curl -X POST 'https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/46ac26bf-69d7-42b2-8d68-477dd745d917/userMessage' \
  -H 'X-Answers-AGS: 2dd5cd0dda1572e964cc2243693c1c08b41b24db80324d663da3f3c661fcd7339744217c450965141f54f3dedf8ffbf01d19c5ac20971993e3f2e55ff0354c08589ce5bea6130285b7d1ba4cc9fbd655702b96493c3947fb464f92b1c50e9713cd214a7d61b2d350411d4efe210ef571' \
 -H 'Content-Type: application/json; charset=utf-8' \
 -H 'Accept: application/json'  \
 --data-binary '{"content":"hello"}'

The header is valid for 24 hours.

Chat Endpoints

Automatic Actions and Webhooks

Some API methods trigger Wix Answers to process automatic actions, and some API methods trigger a call to a relevant webhook: see here and here. These are noted.

User Chat Endpoints

The following endpoints are intended for use by a customer.

Start Chat as a User

Authorization Token for Unauthenticated User

When starting a chat for an unauthenticated user, see Chat Unauthenticated User Header.

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new

Start a chat as a user. Wix Answers creates a ticket for the new chat.

After creating the ticket, Wix Answers processes any automatic actions and then invokes the Ticket Created webhook.

Authorization: None, or a user authorization token for specific user. See Chat Unauthenticated User Header.
Content type: application/json; charset=utf-8
Accept: application/json
Response: Structure, see below

Payload Params	Description	Type	Required
widgetId	The widget in which the chat is initiated	GUID	✓
locale	The chat locale	Language code string, for example: 'de'	✓
userEmail	The user's email address	String
userFirstName	The user's first name	String
customFields	Map of ticket custom field values, each field entry a structure of: * <API field name> (string): The API name of the field (auto-generated; see Finding a Custom Field Name) * <Custom Field value> (format depends on the field)	Structure
labelIds	List of associated labels	List of GUIDs
assignedUserId	The agent the ticket will be assigned to. Do not send this parameter and also assignedGroupId. If sent together with assignedGroupId, the request fails.	GUID
assignedGroupId	The agent group the ticket will be assigned to. Don't send this parameter and also assignedUserId. If sent together with assignedUserId, the request fails.	GUID
subject	Chat subject, if any	String If left empty, the default subject is Chat from %s widget, where %s is the translated widget name.
content	Initial chat message	String
attachments	Attachments to the initial chat message, if any	List of Attachment objects

Payload Example:

1
2
3
4
5
6
7
8
POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new

{
    "widgetId": "bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa",
    "locale": "en",
    "userEmail": "example@domain.us",
    "userFirstName": "Jane"    
}

The response is as follows:

Response Params	Description	Type
userId	The user who initiated the chat	GUID
ticketId	The ticket created for this chat	GUID
ticket	The ticket created for this chat	Ticket Object
assignedGroupId	Group assigned to this ticket	GUID
chatMessage	The initial chat message	Chat Message Object

Response Example:

1
2
3
4
{
    "userId": "aa948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa",
    "ticketId": "ccbd9e6d-bbfd-3cf0-86f3-236a0ae7fafe"
}

Get Your Chat Information

GET https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/my?widgetId={widget GUID}

Get information about all of your chats. For unauthenticated users, only this session is returned; there is no record of this user's previous chat sessions.

Authorization: A user authorization token for specific user. See Chat Unauthenticated User Header.
Content type: application/json; charset=utf-8
Accept: application/json
Response: List of Chat Info Objects

Request Params	Description	Type	Required
widgetId	The widget ID	GUID	✓

Request Example:

1
GET https://<tenant_subdomain>.wixanswers.com/api/v1/chats/my?widgetId=aa948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa

Update Your User Information in Chat

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/user

Update your chat user information. This does not change your existing user record, if any.

Authorization: A user authorization token for specific user. See Chat Unauthenticated User Header.
Content type: application/json; charset=utf-8
Accept: application/json
Response: None

Payload Params	Description	Type	Required
email	The user's email address	String	✓
firstName	The user's first name	String

Payload Example:

1
2
3
4
5
6
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/user

{
    "email": "example@domain.us",
    "firstName": "Jane"    
}

Add User Chat Message

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/{ticket GUID}/userMessage

Send a user chat message to a chat.

Authorization: A user authorization token for specific user. See Chat Unauthenticated User Header.
Content type: application/json; charset=utf-8
Accept: application/json
Response: Chat Message Object

Payload Params	Description	Type	Required
content	The chat message	String
attachments	Attachments to the message, if any	List of Attachment objects

Payload Example:

1
2
3
4
5
6
POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/ccbd9e6d-bbfd-3cf0-86f3-236a0ae7fafe/userMessage

{
    "content": "Hi, Wix Answers",
    "attachments": [ @Attachment object ]
}

Mark Chat Messages Read

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/messages/markSeen

Mark messages as seen up to the specified message ID

Authorization: A user authorization token for specific user. See Chat Unauthenticated User Header.
Content type: application/json; charset=utf-8
Accept: application/json
Response: None

Payload Params	Description	Type	Required
id	The ticket ID	Ticket GUID	✓
lastSeenMessageId	The last seen chat message	Chat message GUID	✓

Payload Example:

1
2
3
4
5
6
POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/messages/markSeen

{
    "id": "bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa",
    "lastSeenMessageId": "e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a"
}

Get Top Active Agents in Chat

GET https://<tenant_subdomain>.wixanswers.com/api/v1/chats/agents/active/top

Get the current list of most active agent names.

Authorization: A user authorization token for specific user. See Chat Unauthenticated User Header.
Content type: application/json; charset=utf-8
Accept: application/json
Response: List of structures, see below

Request Example:

1
GET https://<tenant_subdomain>.wixanswers.com/api/v1/chats/agents/active/top

The response is a list of agent names, as follows:

Response Params	Description	Type
firstName	First name of the agent	String
profileImage	URL of the agent's profile image	String

Response Example:

1
2
3
4
5
6
7
8
9
10
[
  {
    "firstName": "Jane",
    "profileImage": "http://url/of/image"
  },
  {
    "firstName": "Patel",
    "profileImage": "http://Another url/of/image"
  }
]

End Chat by User

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/{ticket GUID}/users/end

End a chat as a user.

This method invokes the Chat Ended Webhook. All agents also leave the chat, so Wix Answers invokes the Agent Left Chat webhook. Wix Answers changes the ticket status to Solved, so Wix Answers invokes the Ticket Status Changed webhook.

Authorization: A user authorization token for specific user. See Chat Unauthenticated User Header.
Content type: application/json; charset=utf-8
Accept: application/json
Response: None

No payload is expected and the endpoint does not send a response.

Agent Chat Endpoints

The following endpoints are intended for use by an agent.

Start Outbound Chat as an Agent

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/outbound

As an agent, start a chat and open a ticket with one or more users. Wix Answers creates a ticket for each user.

After creating the ticket, Wix Answers invokes the Ticket Created webhook.

You should immediately follow this with a call to Add Agent Chat Message. If a user has the widget open, a notification appears; for more information, see the Widget Client SDK. Otherwise, have a webhook send a notification to the user's device.

Authorization: Requires agent authorization token and permission CREATE_CHAT_TICKETS
Content type: application/json; charset=utf-8
Accept: application/json
Response: Structure, see below

The payload for this method includes all parameters presented in Add a Ticket as an Authenticated User, as well as the following:

Payload Params	Description	Type	Required
widgetId	The widget to which the chat is associated	GUID	✓
userIds	List of users to which to initiate chats	List of user GUIDs Minimum 1, maximum 20	At least one user is required

Payload Example:

1
2
3
4
5
6
7
POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/outbound

{
  "widgetId": "e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a",
  "userIds": ["d367738e-368e-41fe-9289-1a5cbbc3c239"],
  ... any relevant ticket parameters ...
}

The response is a structure, as follows:

Response Params	Description	Type
tickets	The new tickets	List of Ticket Objects
failedUserErrors	A map of users to the errors received when trying to initiate a chat with them, pairs of: * User GUID * Error object	Structure

Response Example:

1
2
3
4
5
6
7
{
  "tickets": [@Ticket object],
  "faileduserErrors": {
    "77bc8694-5ccf-436c-ab2b-543563a5f425",
    {"errorCode": "-50006", "message": "NOT_FOUND"}
  }
}

Add Agent Chat Message

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/{ticket GUID}/agentMessage

As an agent, send a chat message to an existing chat.

If this is the agent's first message in this chat, Wix Answers invokes the Agent Joined Chat webhook. If the agent leaves the chat after this message (newTicketStatus is set and endHandling or endAllHandling = true), Wix Answers invokes the Agent Left Chat webhook. Wix Answers also invokes the Agent Replied in Chat webhook. If the ticket status changes to Solved or Closed, Wix Answers invokes the Ticket Status Changed webhook and Chat Ended Webhook.

Authorization: Requires agent authorization token and permission PARTICIPATE_IN_CHATS
Content type: application/json; charset=utf-8
Accept: application/json
Response: Chat Message Object

Payload Params	Description	Type
status	Chat message status	Integer The default is 30 (sent). For phone messages, the default is queued (10).
newTicketStatus	New ticket status, if any	Integer
endHandling	Whether to end your own handling of this ticket This parameter is relevant only if newTicketStatus is set. Only endHandling or endAllHandling can be set to true, not both.	Boolean
endAllHandling	Whether to end all agents' handling of this ticket This parameter is relevant only if newTicketStatus is set. Only endHandling or endAllHandling can be set to true, not both.	Boolean
content	Chat message content	String The default is an empty string.
channel	Channel value	Integer The default (and recommended) value is 161: outbound chat.
attachments	Attachments to the message, if any	List of Attachment objects
chatChannelData	Additional data for channel See outbound chat in Channel.	Structure

Payload Example:

1
2
3
4
5
6
POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/agentMessage

{
  "ticketId": "e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a",
  "content": "Text of message"
}

Search Chat Messages by Date

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/messages/search

Get all chat messages from all tickets during a specific time period.

Authorization: Requires agent authorization token and permission FETCH_CHAT_TICKETS
Content type: application/json; charset=utf-8
Accept: application/json
Response: Structure including list of Chat Message Objects (extended level)

Payload Params	Description	Type	Required
dateFrom	Filter by chat messages from or after this time	Unix time string	✓
dateTo	Filter by chat messages to or before this time	Unix time string	✓
page	Page of results	Integer, minimum 1
size	Number of results on each page	Integer, between 1 and 1000

Payload Example:

1
2
3
4
5
6
7
8
POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/messages/search

{
  "dateFrom": 1623757873,
  "dateTo": 1623757895,
  "page": 1,
  "size": 20
}

Response Example:

1
2
3
4
5
6
7
8
9
{
  "items": [ List of @Chat Message objects ],
  "itemsCount": 108,
  "size": 20,
  "page": 2,
  "numPages": 6,
  "previousPage": 1,
  "nextPage": 3
}

Update Chat Message

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/{ticket GUID}/messages/{chat message GUID}

As an agent, update a chat message's contents.

Authorization: Requires agent authorization token and permission MANAGE_TICKET_REPLIES
Content type: application/json; charset=utf-8
Accept: application/json
Response: Chat Message Object

Payload Params	Description	Type	Required
content	The updated chat message	String	✓

Payload Example:

1
2
3
4
5
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/messages/e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a

{
  "content": "Oops, I meant to write this, instead."
}

Delete Chat Message

DELETE https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/{ticket GUID}/messages/{chat message GUID}

As an agent, delete a chat message.

Authorization: Requires agent authorization token and permission MANAGE_TICKET_REPLIES
Content type: application/json; charset=utf-8
Accept: application/json
Response: None

Request Example:

1
DELETE https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/messages/e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a

Leave Chat as an Agent

Use the method End Handling a Ticket (Agent).

End Chat by Agent

Ticket Status

You can also end a chat if you set the ticket status to Solved or Closed, for example using the method Update a Ticket's Status.

POST https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/{ticket GUID}/agents/end

As an agent, end a chat.

This method invokes the Chat Ended Webhook. All agents also leave the chat, so Wix Answers invokes the Agent Left Chat webhook. If you change a ticket status to Solved or Closed, Wix Answers invokes the Ticket Status Changed webhook.

Authorization: Requires agent authorization token and permission PARTICIPATE_IN_CHATS
Content type: application/json; charset=utf-8
Accept: application/json
Response: None

Payload Params	Description	Type	Required
status	New ticket status, if any	Integer	✓

Payload Example:

1
2
3
4
5
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/chats/new/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/messages/e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a/agents/end

{
  "status": 140
}

Also see Chat Ended Webhook.

Agent Joined Chat / Agent Left Chat

Enabling Webhooks

These options are not visible in the UI. Contact support to enable these webhooks.

The relevant webhook is triggered when an agent joins / leaves a chat with a user. The payload includes the Agent object and the ticket GUID. For the parameter webhookType, 20 indicates AGENT_JOINED_CHAT and 21 indicates AGENT_LEFT_CHAT.

content-type: application/json; charset=utf-8

Example JSON of posted data sent when an agent joins a chat:

1
2
3
4
5
6
7
8
9
{
  "payload": {
    "agent": { @Agent object },
    "ticketId": "5473afb1-921f-4c79-bbf2-3bc2eebe26b4"
  },
  "url": "https://your.endpoint/for/webhook",
  "webhookType": 20,
  "timestamp": 1592299450671
}

Agent Replied in Chat

Enabling Webhook

This option is not visible in the UI. Contact support to enable the webhook.

This webhook is triggered when an agent writes a chat message in a chat with a user. The payload includes the GUID of the chat message (id), ticket (ticketId), ticket owner (ticketOwner), containing chat (chatId), and agent (userId), as well as the agent's User object. The parameter webhookType is always 22, which indicates AGENT_REPLIED_ON_CHAT.

content-type: application/json; charset=utf-8

Example JSON of posted data sent when an agent joins a chat:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "payload": {
    "id": "01e34e53-a249-4f62-ac0d-861e08e819f3",
    "ticketId": "82e2a6d2-fea2-4164-ba45-507a79b9a065",
    "ticketOwner": "282be497-4098-48d4-b30e-22c6ef27117d",
    "text": "<div>This is a chat message.</div>",
    "creationDate": 1592299449316,
    "chatId": "f162ad39-7b65-4e14-8acb-7b3481abd219",
    "deleted": false,
    "user": { @User object },
    "content": "<div>This is a chat message.</div>",
    "userId": "ba1f9474-f68c-4071-ac02-8c8991bd71f8",
    "byAgent": true
  },
  "url": "https://your.endpoint/for/webhook",
  "webhookType": 22,
  "timestamp": 1592299450671
}

Was this article helpful?

Yes

Overview

Wix Answers Developers Overview

The WIX Answers REST API enables you to use code to interact with the Wix Answers back-end. You can use the API to create webhooks that interact with the Wix Answers front and back-ends, or create a new front-e

13 min read

Wix Answers Help Center

Chats API

Chat Unauthenticated User Header

Chat Endpoints

User Chat Endpoints

Start Chat as a User

Get Your Chat Information

Update Your User Information in Chat

Add User Chat Message

Mark Chat Messages Read

Get Top Active Agents in Chat

End Chat by User

Agent Chat Endpoints

Start Outbound Chat as an Agent

Add Agent Chat Message

Search Chat Messages by Date

Update Chat Message

Delete Chat Message

Leave Chat as an Agent

End Chat by Agent

Agent Joined Chat / Agent Left Chat

Agent Replied in Chat

Related Articles

Overview

Wix Answers Developers Overview

The WIX Answers REST API enables you to use code to interact with the Wix Answers back-end. You can use the API to create webhooks that interact with the Wix Answers front and back-ends, or create a new front-e

Wix Answers Help Center

Chats API

Chat Unauthenticated User Header

Chat Endpoints

User Chat Endpoints

Start Chat as a User

Get Your Chat Information

Update Your User Information in Chat

Add User Chat Message

Mark Chat Messages Read

Get Top Active Agents in Chat

End Chat by User

Agent Chat Endpoints

Start Outbound Chat as an Agent

Add Agent Chat Message

Search Chat Messages by Date

Update Chat Message

Delete Chat Message

Leave Chat as an Agent

End Chat by Agent

Chat-Related Webhooks

Agent Joined Chat / Agent Left Chat

Agent Replied in Chat

Related Articles

Overview

Wix Answers Developers Overview

The WIX Answers REST API enables you to use code to interact with the Wix Answers back-end. You can use the API to create webhooks that interact with the Wix Answers front and back-ends, or create a new front-e