Migration Rest Portal

Build Apps

Go Headless

Client

API Preview

Develop Websites

REST

To use the Inbox API, install the `@wix/inbox` package using npm or Yarn:
  ```console
npm install @wix/inbox
```

or

```console
yarn add @wix/inbox
```

Then import `inbox` from `@wix/inbox`:

```js
import inbox from '@wix/inbox'
```
  

inbox

Retrieves a conversation by conversation ID.

If you don't have the conversation ID,
use [`getOrCreateConversation()`](#get-or-create-conversation)
to retrieve the conversation with the visitor, contact, or member ID.

getConversation

Retrieves a conversation for the specified visitor, contact, or member ID,
or creates one if it doesn't exist.

getOrCreateConversation

To use the Conversations API, install the `@wix/inbox` package using npm or Yarn:
  ```console
npm install @wix/inbox
```

or

```console
yarn add @wix/inbox
```

Then import `{ conversations }` from `@wix/inbox`:

```js
import { conversations } from '@wix/inbox'
```
  

Conversations

Retrieves messages between the business and participant.


Up to 30 messages are returned per request.
If the number of messages is larger than the returned page,
`pagingMetadata.cursors` is returned in the response,
indicating that another page of results is available.
To retrieve the next page,
pass the `next` cursor value
in the next request's `paging.cursor` parameter.

To ensure you'll always retrieve the next record,
use the same visibility and sorting
in the first request and all subsequent requests.

By default,
30 messages are retrieved,
sorted by `sequence` in descending order
(the most recent messages are first in the list).

listMessages

Sends a message to the business or participant.


Specify the message type in `message.content`
by including the appropriate object: `basic`, `template`, `minimal`, or `form`.
For more information on message types
and how each type renders in Inbox and the Chat widget,
see [Message Types](#message-types).

sendMessage

To use the Messages API, install the `@wix/inbox` package using npm or Yarn:
  ```console
npm install @wix/inbox
```

or

```console
yarn add @wix/inbox
```

Then import `{ messages }` from `@wix/inbox`:

```js
import { messages } from '@wix/inbox'
```
  

Messages

ChannelType

Conversation

string

Display name and avatar for the business.

businessDisplayData

ConversationDisplayData

List of communication channels where the visitor, contact, or member can receive messages.

channels

ID of the visitor, contact, or member who is chatting with the business.

participant

IdentificationData

Display name and avatar for the visitor, contact, or member.

participantDisplayData

imageUrl

name

GetConversationResponse

conversation

GetOrCreateConversationOptions

ID of the visitor, contact, or member chatting with the business.

Required for 3rd-party apps.

participantId

ParticipantId

GetOrCreateConversationResponse

Indicates whether the conversation was just created.

If `true`, the conversation was just created.
If `false`, the conversation already existed.

newConversation

boolean

anonymousVisitorId

ID of a site
[member](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Fmember-permissions/members).

memberId

ID of a site
[contact](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Fcontacts).

contactId

Badge

Controls whether the badge is visible to the participant.
Currently not supported in the Chat widget.

badgeVisibility

BadgeVisibility

iconUrl

text

BasicMessageData

File attachment.
Can contain a file from Wix Media or an external provider.

file

Image message.
Can contain an image from Wix Media
or from an external provider.

image

BasicMessagePayload

List of plain text messages, images, and/or files.
List items are displayed as separate messages
in Inbox and the site's chat widget.

items

Button

label

If included, the button launches the specified URL.

launchUrl

Properties to pass to the
[Button Interacted webhook](https://dev.wix.com/api/rest/inbox/messages/button-interacted-webhook)
when the button is clicked.

postbackProperties

PostbackProperties

CursorPaging

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

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

cursor

limit

number

Cursors

Cursor pointing to next page in the list of results.

FileMessage

filename

File [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types).

mimeType

FormField

value

FormMessagePayload

Form description displayed below the title.

description

fields

List of files and/or images attached to the form.

List items are displayed as separate messages
in Inbox and the site's chat widget.

media

title

appId

Site
[member](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Fmember-permissions/members)
ID.

User ID of the site owner or a site contributor.

wixUserId

Optional site
[contact](https://www.wix.com/my-account/site-selector/?buttonText=Select%20Site&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https:%2F%2Fwww.wix.com%2Fdashboard%2F%7B%7BmetaSiteId%7D%7D%2Fcontacts) ID.

ImageMessage

height

width

ListMessagesOptions

paging

sorting

Sorting

__Required.__
Filters for messages with the specified visibility setting.

- `BUSINESS_AND_PARTICIPANT`: Return messages visible to the business and the participant.
- `BUSINESS`: Return all messages.

visibility

MessageVisibility

ListMessagesResponse

List of messages between the specified visitor and the site.

messages

Details on the paged set of results returned.

pagingMetadata

PagingMetadataV2

MediaItem

Message

_createdDate

ID of the application that sent the message.

Omitted if the message was sent with the Chat widget.

Optional icon and short text
that give an additional detail about the message,
such as the app the message was sent from
or whether the message was an automated response.

Currently only 1 badge is supported.

badges

content

MessageContent

__Required.__
Message direction.

- `BUSINESS_TO_PARTICIPANT`: The message was sent from the business to the participant.
- `PARTICIPANT_TO_BUSINESS`: The message was sent from the participant to the business.

direction

MessageDirection

ID of the message sender.

Defaults to the caller's ID
using the property that matches their identity type.
For 3rd-party apps, defaults to using the app's `appId`.

You can override the default behavior when calling
[`sendMessage()`](#sendmessage)
by using the `sendAs` option.

sender

Sequential ordering of the message.
Ensures more accurate sorting than `createdDate`
if two messages are sent at the same time.

sequence

Communication channel the message is sent from.

sourceChannel

Communication channel to send the message to.

Currently messages can be sent to 1 channel only.

targetChannels

__Required.__
Controls who can see the message.

- `BUSINESS_AND_PARTICIPANT`: Visible to the participant and site contributors.
- `BUSINESS`: Visible to site contributors only.

basic

Message containing submitted form data.
Typically sent with a `direction` of `PARTICIPANT_TO_BUSINESS`
and message `visibility` of `BUSINESS`.

form

Minimal message containing a single line of text
and an optional icon.
Often reports an activity that took place.

minimal

system

Template containing an image, title, text,
and/or up to 10 call-to-action buttons.

template

Summary of message contents.
Displayed in Inbox in the
[Message List](https://support.wix.com/en/article/wix-inbox-getting-started#view-your-messages).

previewText

MinimalMessagePayload

If included, URL the user is redirected to when clicking the message.

Orientation

OverrideSenderOptions

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.

cursors

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

[Your app's](https://dev.wix.com/dc3/my-apps) App ID.

ID you define for the interaction, to be handled by your server.

interactionId

SendMessageOptions

message

Controls which identity to use in the message's `sender` property.

- `CALLER`: Uses the identity included in the request header.
- `PARTICIPANT`: Uses the `anonymousVisitorId`, `contactId`, or `memberId` of the conversation's participant.
- `BUSINESS_USER`: For internal use. Uses the `wixUserId` of the person sending messages on behalf of the business.

Defaults to `CALLER`.
For 3rd-party apps, the app is the caller.

sendAs

Controls whether the message triggers notifications when it's received.

Defaults to `false`.

sendNotifications

Controls whether the unread count and conversation summary
are updated in the
[Message List](https://support.wix.com/en/article/wix-inbox-getting-started#view-your-messages).

If `true`, unread count and conversation summary are not updated.

Defaults to `false`.

silent

SendMessageResponse

SortOrder

fieldName

order

SystemMessagePayload

List of buttons to display with the message.
Buttons can either open a URL or pass interaction details to the
[Button Interacted Webhook](https://dev.wix.com/api/rest/all-apis/inbox/button-interacted-webhook).

Maximum: 10 buttons.

buttons

Text message. `\n` renders as a line break.

TemplateMessagePayload

Controls whether the message is displayed in portrait or landscape layout.

Defaults to `PORTRAIT`.

orientation

List of lines of text. Each item in the array is displayed on a new line.

Maximum: 10 lines, up to 512 characters per line.

Setup