Example Flows

This article shares some possible use cases your app could support, as well as an example flow that could support each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your app's implementation.

Sync Messages from an External Service

Your app can enable business owners to communicate with their customers on any platform by syncing messages to Wix Inbox. The scenario below covers chat messages, but this flow could support integrating phone call logs, SMS services, chat sessions, or any other online or offline communication.

To do this, your app can follow this basic flow:

1. Set up the external service's webhooks. When a "message sent" or "message received" webhook is triggered, parse the event data for an email address.

2. Use Query Contacts to find a contact with the email address you extracted in step 1. You're looking for a contact ID here, so you can use the fields array to make sure the response only passes back id:

   Copy

   1
   {
   2
     "query": {
   3
       "filter": {
   4
         "info.emails.email": { "$eq": "<EMAIL_ADDRESS_FROM_INCOMING_MESSAGE>" }
   5
       },
   6
       "fields": [ "id" ]
   7
     }
   8
   }

   Any matching contacts are in the returned contacts array. An email address can belong to more than one contact, so your app must handle situations when multiple contacts are returned.

3. Get the conversation ID with Get or Create Conversation.

   Set the participantId.contactId parameter to the id extracted in step 2:

   Copy

   1
   {
   2
     "participantId": { "contactId": "4e600edc-db48-5260-9d04-7ea5c3e5fffd" }
   3
   }

   You can get the conversation ID from conversation.id in the response.

4. Use Send Message to add the new message to the contact's conversation.

   Set the conversationId parameter to conversation.id returned in step 3.

   In the body, pass the incoming message in a BASIC message type:

   Copy

   1
   {
   2
     "message": {
   3
   
   4
       // Hides the message from the chat widget when the contact visits the site
   5
       "visibility": "BUSINESS",
   6
   
   7
       "content": {
   8
         "basic": {
   9
           "items": [{ "text": "<INCOMING_MESSAGE_FROM_EXTERNAL_SERVICE>" }]
   10
         }
   11
       },
   12
   
   13
       // Indicates the message came from Facebook
   14
       "badges": [{
   15
         "text": "Facebook",
   16
         "iconUrl": "https://static.wixstatic.com/media/aebe5b6fd55f471a936c72ff2c8289d7.png/v1/fill/w_43,h_43,al_c,q_85,usm_0.66_1.00_0.01/aebe5b6fd55f471a936c72ff2c8289d7.webp"
   17
       }]
   18
     },
   19
   
   20
     // Displays the message as if the contact sent it
   21
     "direction": "PARTICIPANT_TO_BUSINESS"
   22
   }

Your app can also send messages sent on behalf of the business from the external chat tool. In those cases, change the visibility settings to match your requirements, and set direction to BUSINESS_TO_PARTICIPANT.

Add Contact Activities from Another Service

Your app can capture contact activities from another platform and display them in the contact's conversation in Inbox.

To do this, your app can follow this basic flow:

1. Set up the external service's webhooks. When an event webhook is triggered, parse the event data for an email address.

2. Use Query Contacts to find a contact with the email address you extracted in step 1. You're looking for a contact ID here, so you can use the fields array to make sure the response only passes back id:

   Copy

   1
   {
   2
     "query": {
   3
       "filter": {
   4
         "info.emails.email": { "$eq": "<CUSTOMER_EMAIL_ADDRESS>" }
   5
       },
   6
       "fields": [ "id" ]
   7
     }
   8
   }

   The response includes matching contacts in the returned contacts array. An email address can belong to more than one contact, so your app must handle situations when multiple contacts are returned.

3. Get the conversation ID with Get or Create Conversation.

   Set the participantId.contactId path parameter to the id extracted in step 2:

   Copy

   1
   {
   2
     "participantId": { "contactId": "4e600edc-db48-5260-9d04-7ea5c3e5fffd" }
   3
   }

   You can get the conversation ID from conversation.id in the response.

4. Use Send Message to add the new message to the contact's conversation.

   Set the conversationId path parameter to conversation.id returned in step 3.

   In the body, pass the action in a MINIMAL message type:

   Copy

   1
   {
   2
     "message": {
   3
   
   4
       // Hides the message from the chat widget when the contact visits the site
   5
       "visibility": "BUSINESS",
   6
   
   7
       "payload": {
   8
         "type": "MINIMAL",
   9
         "minimal": {
   10
           "text": "Booked Spa Treatment",
   11
           "iconUrl": "https://static.wixstatic.com/media/bd4a2aff643141cb8cbacde1a4007a2f.png/v1/fill/w_43,h_50,al_c,lg_1,q_85/bd4a2aff643141cb8cbacde1a4007a2f.webp"
   12
         }
   13
       }
   14
     },
   15
   
   16
     // Displays the message as if the contact sent it
   17
     "direction": "PARTICIPANT_TO_BUSINESS"
   18
   }