Message Types

Messages can be sent as different types, allowing for the display to match the message payload. Your app can send messages as basic, template, minimal, or form type. You may see an additional system type in some responses. system type is reserved for internal use for sending messages.

This article gives a brief overview of each of the message types and how to structure the message object in your Send Message request.

Basic Messages

basic messages contain an array of text, image, or file. Array items are displayed in Inbox and the visitor's chat widget as if each item was a separate message.

This example contains an image followed by two text messages:

Copy

1{
2  "message": {
3    "direction": "BUSINESS_TO_PARTICIPANT",
4    "content": {
5      "previewText": "Thanks for booking your spa day with us!",
6      "basic": {
7        "items": [
8          {
9            "image": {
10              "url": "https://static.wixstatic.com/media/f93e3d633e79921f14330f1911fc1139.jpg/v1/fill/w_1200,h_798,al_c,q_85,usm_0.66_1.00_0.01/f93e3d633e79921f14330f1911fc1139.webp",
11              "width": 1200,
12              "height": 798
13            }
14          },
15          { "text": "Thanks for booking your spa day with us!" },
16          { "text": "We've emailed your invoice. You'll find everything you need to know there." }
17        ]
18      }
19    }
20  }
21}

The above example produces this output:

Inbox	Chat Widget

Form Messages

form messages present form data submitted by the participant. Form messages contain a title, an optional description, and an array of fields. Each field in the array has a name and submitted value property.

Form messages are typically sent with a direction of PARTICIPANT_TO_BUSINESS. To hide the message from the visitor, set visibility to BUSINESS.

This example contains 4 form fields and an image:

Copy

1{
2  "message": {
3    "direction": "PARTICIPANT_TO_BUSINESS",
4    "visibility": "BUSINESS",
5    "content": {
6      "previewText": "JoJo Doe made an appointment",
7      "form": {
8        "title": "New Spa Appointment",
9        "description": "JoJo Doe made an appointment",
10        "fields": [
11          { "name": "First Name", "value": "JoJo" },
12          { "name": "Last Name", "value": "Doe" },
13          { "name": "Treatments", "value": "Massage, Mud Bath, Facial" },
14          { "name": "Appointment Date", "value": "May 9, 2021" }
15        ],
16        "media": [
17          {
18            "image": {
19              "url": "https://static.wixstatic.com/media/f93e3d633e79921f14330f1911fc1139.jpg/v1/fill/w_1200,h_798,al_c,q_85,usm_0.66_1.00_0.01/f93e3d633e79921f14330f1911fc1139.webp",
20              "width": 1200,
21              "height": 798
22            }
23          }
24        ]
25      }
26    }
27  }
28}

The above example is not displayed in the visitor's chat widget because visibility is set to BUSINESS. It produces this output in Inbox:

Inbox

Minimal Messages

minimal messages contain a single line of text and an optional icon. They're useful for reporting an activity that took place. To hide the message from the visitor, set visibility to BUSINESS.

This example reports that the visitor made a spa appointment:

Copy

1{
2  "message": {
3    "direction": "PARTICIPANT_TO_BUSINESS",
4    "visibility": "BUSINESS",
5    "content": {
6      "previewText": "Booked a spa appointment",
7      "minimal": {
8        "text": "Booked a spa appointment",
9        "iconUrl": "https://static.wixstatic.com/media/727514_1a58537f1b6a44a7b09956cdbc5ac774~mv2.png/v1/fill/w_297,h_324,al_c,lg_1,q_85/727514_1a58537f1b6a44a7b09956cdbc5ac774~mv2.webp"
10      }
11    }
12  }
13}

The above example is not displayed in the visitor's chat widget because visibility is set to BUSINESS. It produces this output in Inbox:

Inbox

Template Messages

template messages use buttons to allow the visitor to perform actions. Buttons can be either ACTION or POSTBACK type. Action buttons open a specified url in the visitor's browser, and postback buttons pass a buttonPayload to the Button Interacted Webhook.

This example tells the visitor their spa appointment has been booked and offers two buttons. The first is an action button, and the second is a postback button:

Copy

1{
2  "message": {
3    "direction": "BUSINESS_TO_PARTICIPANT",
4    "content": {
5      "previewText": "JoJo, you're getting a spa day!",
6      "template": {
7        "title": "JoJo, you're getting a spa day!",
8        "imageUrl": "https://static.wixstatic.com/media/f93e3d633e79921f14330f1911fc1139.jpg/v1/fill/w_1200,h_798,al_c,q_85,usm_0.66_1.00_0.01/f93e3d633e79921f14330f1911fc1139.webp",
9        "textLines": [
10          "Thanks for booking with us!",
11          "You're booked for a massage, mud bath, and facial on May 9, 2021."
12        ],
13        "buttons": [
14          {
15            "label": "View My Invoice",
16            "launchUrl": "https://www.example.com/customer_12345/spa_day_54321/invoice.pdf"
17          },
18          {
19            "label": "Change My Appointment",
20            "postbackProperties": { "interactionId": "spa_day_54321__change_appointment" }
21          }
22        ]
23      }
24    }
25  }
26}

The above example produces this output:

Inbox	Chat Widget

System Messages

system messages convey system information from an integrated service such as Facebook or Instagram.

System messages cannot be sent by 3rd-party apps. However, your app may still need to consume system messages.

This example payload contains text and a "Learn More" link:

Copy

1{
2  "message": {
3    "direction": "PARTICIPANT_TO_BUSINESS",
4    "visibility": "BUSINESS",
5    "sourceChannel": "FACEBOOK",
6    "content": {
7      "previewText": "Facebook policy requires you to respond to\nvisitors' messages within 7 days.",
8      "system": {
9        "text": "Facebook policy requires you to respond to\nvisitors' messages within 7 days.",
10        "buttons": [
11          {
12            "label": "Learn More",
13            "launchUrl": "https://support.wix.com/en/article/wix-inbox-connecting-your-facebook-page"
14          }
15        ]
16      }
17    }
18  }
19}

The above example produces this output:

Inbox

Was this helpful?

Yes

Message Object

Properties

idstringRead-only

Message ID.

contentobject

Structured message content.

senderobject

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 Send Message by using the sendAs parameter.

badgesArray <Badge>maxItems 1

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.

targetChannelsArray <string>

Communication channel to send the message to. Currently messages can be sent to 1 channel only.

sourceChannelstring

7 enum supported values:

UNKNOWN_CHANNEL_TYPECHATEMAILSMSFACEBOOKINSTAGRAMWHATSAPP

Communication channel the message is sent from.

appIdstringRead-onlyformat GUID

ID of the application that sent the message. Omitted if the message was sent with the Chat widget.

visibilitystring

3 enum supported values:

UNKNOWN_VISIBILITYBUSINESS_AND_PARTICIPANTBUSINESS

Required. Controls who can see the message.

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

sequenceobjectRead-only

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

directionstring

3 enum supported values:

UNKNOWN_DIRECTIONBUSINESS_TO_PARTICIPANTPARTICIPANT_TO_BUSINESS

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.

createdDatestringformat date-time

Date and time the message was sent.

Was this helpful?

Yes

GetList Messages

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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).

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Endpoint

GET

https://www.wixapis.com/inbox/v2/messages

Was this helpful?

Yes

PostSend Message

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

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.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/inbox/v2/messages

Was this helpful?

Yes

Message Sent To Participant

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when the business sends a message to a visitor, contact, or member.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.

Event Data

idstring

Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.crm.inbox.v2.message.

slugstring

Event name. Expected message_sent_to_participant.

entityIdstring

ID of the entity associated with the event.

eventTimestringformat date-time

Event timestamp.

triggeredByAnonymizeRequestboolean

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

originatedFromstring

If present, indicates the action that triggered the event.

actionEventobject

Event information.

Was this helpful?

Yes

Message Sent To Business

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a visitor, contact, or member sends a message to the business.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.

Event Data

idstring

Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.crm.inbox.v2.message.

slugstring

Event name. Expected message_sent_to_business.

entityIdstring

ID of the entity associated with the event.

eventTimestringformat date-time

Event timestamp.

triggeredByAnonymizeRequestboolean

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

originatedFromstring

If present, indicates the action that triggered the event.

actionEventobject

Event information.

Was this helpful?

Yes

Button Interacted

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when a postback button is clicked.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.

Event Data

idstring

Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring

Fully qualified domain name of the entity associated with the event. Expected wix.crm.inbox.v2.message.

slugstring

Event name. Expected button_interacted.

entityIdstring

ID of the entity associated with the event.

eventTimestringformat date-time

Event timestamp.

triggeredByAnonymizeRequestboolean

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

originatedFromstring

If present, indicates the action that triggered the event.

actionEventobject

Event information.

Was this helpful?

Yes