Coding Examples

Go Headless

Build Apps

Client

API Preview

Ricos

Develop Websites

REST

Velo

Picasso

GraphQL (Alpha)

# About the Messages API

The Wix AI Site-Chat Messages API enables you to manage site visitor messages to and from the site's AI Site-Chat.

With this API, you can:
- Create messages between a site visitor and the site's AI Site-Chat.
- Retrieve a site visitor's messages to and from the site's AI Site-Chat.

> **Note:** Wix AI Site-Chat is currently only available in the Wix Editor.


## Before you begin
It's important to note the following points before starting to code:
* Sites using this API must install the [Wix AI Site-Chat](fallback::https://www.wix.com/app-market/web-solution/wix-ai-assistant-client) app. Learn more about [adding and setting up Wix AI Site-Chat](fallback::https://support.wix.com/en/article/adding-and-setting-up-the-wix-ai-chat-assistant).
* The methods in this API must be called using the [site visitor or site member identity](fallback::https://dev.wix.com/docs/rest/articles/getting-started/about-identities#site-member) to identify the site visitor that is creating or retrieving the messages. Therefore, [Wix apps](fallback::https://dev.wix.com/docs/build-apps) can't currently call theses method using REST.

## Use cases
- [Check that a response has been sent to every message from the site visitor](fallback::https://dev.wix.com/docs/rest/business-management/ai-site-chat/ai-site-chat/messages/sample-flows#check-that-a-response-has-been-sent-to-every-message-from-the-site-visitor)


# Messages: Sample Use Cases and Flows

This article shares a possible use case your app or site could support, as well as a sample flow. This can be a helpful jumping-off point.

## Check that a response has been sent to every message from the site visitor
To check that a response has been sent to every message from the site visitor:

1. Call [List Messages](fallback::https://dev.wix.com/docs/rest/business-management/ai-site-chat/ai-site-chat/messages/list-messages).
1. Create a copy of the messages returned in the response to include only messages sent by the site visitor. Call these "questions".
1. For each "question", iterate over the messages returned in the response to check if one exists that's an `answerTo` the "questions".
1. Call [Bulk Create Messages](fallback::https://dev.wix.com/docs/rest/business-management/ai-site-chat/ai-site-chat/messages/bulk-create-messages) to send "answers" to all the unanswered "questions".

identityType

IdentificationData

WebhookIdentityType

ID of a site visitor that has not logged in to the site.

anonymousVisitorId

appId

ID of a site visitor that has logged in to the site.

memberId

ID of a Wix user (site owner, contributor, etc.).

wixUserId

data

eventType

The identification type and identity data.

instanceId

MessageEnvelope

value

BoolValue

Int32Value

Int64Value

values

ListValue

NullValue

StringValue

fields

Struct

nanos

seconds

Timestamp

Value

boolValue

listValue

nullValue

numberValue

stringValue

structValue

kind

Extended field data. Each key corresponds to the namespace of the app that created the extended fields.
The value of each key is structured according to the schema defined when the extended fields were configured.

You can only access fields for which you have the appropriate permissions.

Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields).

namespaces

ExtendedFields

bodyAsJson

ActionEvent

A sequence number defining the order of updates to the underlying entity.
For example, given that some entity was updated at 16:00 and than again at 16:01,
it is guaranteed that the sequence number of the second update is strictly higher than the first.
As the consumer, you can use this value to ensure that you handle messages in the correct order.
To do so, you will need to persist this number on your end, and compare the sequence number from the
message against the one you have stored. Given that the stored number is higher, you should ignore the message.

entityEventSequence

Assumes actions are also always typed to an entity_type
Example: wix.stores.catalog.product, wix.bookings.session, wix.payments.transaction

entityFqdn

ID of the entity associated with the event.

entityId

Event timestamp in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format and UTC time. For example: 2020-04-26T13:57:50.699Z

eventTime

Unique event ID.
Allows clients to ignore duplicate webhooks.

If present, indicates the action that triggered the event.

originatedFrom

This is top level to ease client code dispatching of messages (switch on entity_fqdn+slug)
This is although the created/updated/deleted notion is duplication of the oneof types
Example: created/updated/deleted/started/completed/email_opened

slug

Whether the event was triggered as a result of a privacy regulation application
(for example, GDPR).

triggeredByAnonymizeRequest

DomainEvent

body

entityAsJson

Indicates the event was triggered by a restore-from-trashbin operation for a previously deleted entity

EntityCreatedEvent

deletedEntityAsJson

EntityDeletedEvent

Since platformized APIs only expose PATCH and not PUT we can't assume that the fields sent from the client are the actual diff.
This means that to generate a list of changed fields (as opposed to sent fields) one needs to traverse both objects.
We don't want to impose this on all developers and so we leave this traversal to the notification recipients which need it.

currentEntityAsJson

EntityUpdatedEvent

deletedDate

RestoreInfo

additionalData

footerText

mainText

Body

messages

BulkCreateMessagesRequest

BulkCreateMessagesResponse

Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`.

ListMessagesRequest

ListMessagesResponse

ID of the message that this message is answering.

answerTo

conversationId

createdDate

messageType

sender

Message

Intro message, as defined in the widget settings.

Legal disclaimer, as defined in the widget settings.

Message confirms that a contact form was successfully submitted.

Message informing the site visitor that the AI assistant is offline, as defined in the widget settings.

Message that informs the Wix user that they have reached the maximum number of messages on their current plan.

MessageType

Message was sent automatically due to widget settings. For example, a contact form.

Sender

Pointer to the next or previous page in the list of results.

Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response.
Not relevant for the first request.

cursor

Maximum number of items to return in the results.

limit

CursorPaging

Cursor string pointing to the next page in the list of results.

Cursors

Number of items returned in the response.

count

Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used.

offset

Flag that indicates the server failed to calculate the `total` field.

tooManyToCount

Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set.

total

PagingMetadataV2

Bulk creates messages.

This method must be called using the site visitor or site member identity ([SDK](https://dev.wix.com/docs/sdk/articles/get-started/about-identities#site-member) | [REST](https://dev.wix.com/docs/rest/articles/getting-started/about-identities#site-member)) to identify the site visitor that is creating the messages.

Retrieves a list of messages.

Up to 100 Messages can be returned per request.

This method must be called using the site visitor or site member identity ([SDK](https://dev.wix.com/docs/sdk/articles/get-started/about-identities#site-member) | [REST](https://dev.wix.com/docs/rest/articles/getting-started/about-identities#site-member)) to identify the site visitor that is retrieving the messages.

Message Object