Migration Rest Portal

Build Apps

Go Headless

Client

API Preview

Develop Websites

REST

GraphQL (Alpha)

conversationId

string

Retrieves a conversation by conversation ID.

If you don't have the conversation ID, use `getOrCreateConversation()` to retrieve the conversation using the visitor, contact, or member ID.

import { conversations } from 'wix-inbox.v2';

/* Sample conversationID value: '092d1135-99cf-3ca9-a0bf-378e1df4539b' */

export async function myGetConversationFunction(conversationId) {
  
  try {
    const conversationObject = await conversations.getConversation(conversationId);
    const channels = conversationObject.conversation.channels;
    const firstChannel = conversationObject.conversation.channels[0];
    const businessName = conversationObject.conversation.businessDisplayData.name;

    return conversationObject;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
}

/* Promise resolves to:
 *  {
 *    "conversation": {
 *      "_id": "6fd2b962-dd8f-382f-8d27-ae63f188c939",
 *      "businessDisplayData": {
 *        "name": "Tim's Cookies"
 *      },
 *      "channels": [
 *        "CHAT",
 *        "EMAIL"
 *      ],
 *      "participant": {
 *        "contactId": "9e668c08-8bdb-4240-babb-8176935f6f78"
 *      },
 *      "participantDisplayData": {
 *        "name": "jsmith@example.com"
 *      }
 *    }
 *  }
 */

Get a conversation (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { conversations } from 'wix-inbox.v2';
import { elevate } from 'wix-auth';

/* Sample conversationID value: '092d1135-99cf-3ca9-a0bf-378e1df4539b' */

export const myGetConversationFunction = webMethod(Permissions.Anyone, async (conversationId) => {
  
  try {
    const elevatedGetConversation = elevate(conversations.getConversation);
    const conversationObject = await elevatedGetConversation(conversationId);
    const channels = conversationObject.conversation.channels;
    const firstChannel = conversationObject.conversation.channels[0];
    const businessName = conversationObject.conversation.businessDisplayData.name;

    return conversationObject;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});

/* Promise resolves to:
 *  {
 *    "conversation": {
 *      "_id": "6fd2b962-dd8f-382f-8d27-ae63f188c939",
 *      "businessDisplayData": {
 *        "name": "Tim's Cookies"
 *      },
 *      "channels": [
 *        "CHAT",
 *        "EMAIL"
 *      ],
 *      "participant": {
 *        "contactId": "9e668c08-8bdb-4240-babb-8176935f6f78"
 *      },
 *      "participantDisplayData": {
 *        "name": "jsmith@example.com"
 *      }
 *    }
 *  }
 */


Get a conversation (export from backend code)

getConversation

Conversation

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

participantId

ParticipantId

Retrieves a conversation by the specified visitor, contact, or member ID. If the conversation does not exist for the provided visitor, contact, or member, the function creates a new conversation.

import { conversations } from 'wix-inbox.v2';
import { elevate } from 'wix-auth';

/* Sample participantId value:
 * {
 *   memberId: 'b17c523c-6ec9-4b56-9d9d-123cc6978bdf'
 * }
 */

export async function myGetOrCreateConversationFunction(participantId) { 
  try {
    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
    const conversationObject = await elevatedGetOrCreateConversation(participantId);
    const id = conversationObject.conversation._id;
    const channels = conversationObject.conversation.channels;
    const siteName = conversationObject.conversation.businessDisplayData.name;
    
    return conversationObject;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
}

/* Promise resolves to:
 * {
 *   "conversation": {
 *     "_id": "092d1135-99cf-3ca9-a0bf-378e1df4539b",
 *     "businessDisplayData": {
 *       "name": "Classic Cars"
 *     },
 *     "channels": [
 *       "CHAT", 
 *        EMAIL
 *     ],
 *     "participant": {
 *       "memberId": "b17c523c-6ec9-4b56-9d9d-123cc6978bdf"
 *     },
 *      "participantDisplayData": {
 *       "name": "alevine@email.com"
 *   }
 *   "newConversation": false
 * }
 */


Get or create a conversation from a member (dashboard page code)

import { Permissions, webMethod } from 'wix-web-module';
import { conversations } from 'wix-inbox.v2';
import { elevate } from 'wix-auth';

/* Sample participantId value:
 * {
 *   memberId: 'b17c523c-6ec9-4b56-9d9d-123cc6978bdf'
 * }
 */

export const myGetOrCreateConversationFunction = webMethod(Permissions.Anyone, async (participantId) => {
  
  try {
    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
    const conversationObject = await elevatedGetOrCreateConversation(participantId);
    const id = conversationObject.conversation._id;
    const channels = conversationObject.conversation.channels;
    const siteName = conversationObject.conversation.businessDisplayData.name;

    return conversationObject;
  } catch (error) {
    console.error(error);
    // Handle the error
  }
});

/* Promise resolves to:
 * {
 *   "conversation": {
 *     "_id": "092d1135-99cf-3ca9-a0bf-378e1df4539b",
 *     "businessDisplayData": {
 *       "name": "Classic Cars"
 *     },
 *     "channels": [
 *       "CHAT", 
 *        EMAIL
 *     ],
 *     "participant": {
 *       "memberId": "b17c523c-6ec9-4b56-9d9d-123cc6978bdf"
 *     },
 *      "participantDisplayData": {
 *       "name": "alevine@email.com"
 *   }
 *   "newConversation": false
 * }
 */


Get or create a conversation from a member (export from backend code)

/*******************************
 * Backend code - inbox.web.js *
 *******************************/

import { Permissions, webMethod } from 'wix-web-module';
import { conversations, messages } from 'wix-inbox.v2';
import { currentMember } from 'wix-members-backend'
import { elevate } from 'wix-auth';

export const sendFormData = webMethod(Permissions.Anyone, async (formData) => {
  const message = {
    direction: 'PARTICIPANT_TO_BUSINESS',
    visibility: 'BUSINESS',
    content: {
      previewText: 'New Contact',
      form: {
        title: 'New Contact',
        description: 'New Contact Form',
        fields: [
          { 
            name: 'First Name', 
            value: formData.firstName
          },
          { 
            name: 'Last Name', 
            value: formData.lastName 
          },
          { 
            name: 'email', 
            value: formData.email 
          },
          { 
            name: 'Wants Newsletter', 
            value: formData.subscribeNewsletter.toString() 
          }
        ],
      }
    }
  }
  
  try {
    const conversationId = await getOrCreateConversationIdFromMember();

    const elevatedSendMessage = elevate(messages.sendMessage);
    const formMessage = await elevatedSendMessage(conversationId, message);

    return formMessage;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});

export const getOrCreateConversationIdFromMember = webMethod(Permissions.Anyone, async () => {
  const member = await currentMember.getMember();
  const participantId = { 
    memberId: member._id 
  };
  
  try {
    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
    const conversationObject = await elevatedGetOrCreateConversation(participantId);
    
    return conversationObject.converation._id;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});
/*************
 * Page code *
 *************/

import { sendFormData } from 'backend/inbox.web';

$w.onReady(function () {
  $w('#submitButton').onClick(async () => {
    const firstName = $w('#firstName').value;
    const lastName = $w('#lastName').value;
    const email = $w('#email').value;
    const subscribeNewsletter = $w('#subscribeNewsletter').checked;
    const dataToInsert = {
      firstName,
      lastName,
      email,
      subscribeNewsletter
    };

    const formData = await sendFormData(dataToInsert);
    console.log(`The form data is ${formData}`);
  });
});

The page code passes input values submitted by a logged-in member to the backend `sendFormData` function. This function retrieves the logged-in member ID, gets an existing or creates a new converation object and uses the conversation ID to send a form message to the site owner's inbox dashboard.

Get or create a new conversation with a member 

/****************************
 * Backend code - events.js *
 ****************************/

import { sendThankYou } from 'backend/inbox';

export function wixCrm_onContactCreated(event) {
  const contactId = event.metadata.entityId;
  sendThankYou(contactId);
}

/*******************************
 * Backend code - inbox.web.js *
 *******************************/

import { Permissions, webMethod } from 'wix-web-module';
import { conversations, messages } from 'wix-inbox.v2';
import { elevate } from 'wix-auth';

export const sendThankYou = webMethod(Permissions.Anyone, async (contactId) => {
  const participantId = {
    contactId: contactId
  };
  const message = {
    direction: 'BUSINESS_TO_PARTICIPANT',
    visibility: 'BUSINESS_AND_PARTICIPANT',
    content: {
      previewText: 'Thank You',
      basic: {
        items: [
          { text: 'Thank you for your input' },
        ]
      }
    },
    sourceChannel: 'CHAT',
    targetChannels: ['CHAT']
  }
  
  try {
    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
    const conversationObject = await elevatedGetOrCreateConversation(participantId);
    const conversationId = conversationObject.conversation._id;

    const elevatedSendMessage = elevate(messages.sendMessage);
    const thankYouMessage = await elevatedSendMessage(conversationId, message);

    return thankYouMessage;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});


This code registers an event listener in the `events.js` file that triggers when a new contact is created. The event handler calls `getOrCreateConversation()` to generate or retrieve a conversation. It then sends a thank-you message in the `wix-chat` widget.

Get or create a conversation with a contact 

import { Permissions, webMethod } from 'wix-web-module';
import { conversations } from 'wix-inbox.v2';
import { elevate } from 'wix-auth';

/* Sample participantId value:
 * {
 *   anonymousVisitorId: 'af63e767-caeb-4435-bf8c-f14ebd413060'
 * }
 */

export const getConversationFromVisitor = webMethod(Permissions.Anyone, async (participantId) => {
  try {
    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation)
    const conversationObject = await elevatedGetOrCreateConversation(participantId);
    const id = conversationObject.conversation._id;
    const firstChannel = conversationObject.conversation.channels[0];

    return conversationObject;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});

/* Promise resolves to:
 * {
 *   "conversation": {
 *     "_id": "c4999cbd-33ea-37cb-a374-75600f409d0b",
 *     "businessDisplayData": {
 *       "name": "Peak Fitness"
 *     },
 *     "channels": [
 *       "CHAT"
 *     ],
 *     "participant": {
 *       "anonymousVisitorId": "5dc5855b-0e34-495b-9762-3a9f591baa37"
 *     },
 *     "participantDisplayData": {
 *       "name": "Visitor #8145",
 *       "imageUrl": "https://static.parastorage.com/services/engage-web/1.6076.0/assets/visitor-avatars-faces/Avatar1Orange.png"
 *     }
 *   },
 *   "newConversation": false
 * }
 */


Get or create a conversation with anonymousVisitorId 

import { Permissions, webMethod } from 'wix-web-module';
import { conversations } from 'wix-inbox.v2';
import { elevate } from 'wix-auth';

/* Sample participantId value:
 * {
 *   contactId: 'c5ef5c35-3b53-41c9-aeeb-214424e5f6e5'
 * }
 */

export const myGetOrCreateConversationFunction = webMethod(Permissions.Anyone, async (participantId) => {
  
  try {
    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
    const conversationObject = await conversations.getOrCreateConversation(participantId);
    const id = conversationObject.conversation._id;
    const channels = conversationObject.conversation.channels;
    const siteName = conversationObject.conversation.businessDisplayData.name;

    return conversationObject;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});

/* Promise resolves to:
 * {
 *   "conversation": {
 *     "_id": "7d313780-d237-3d5e-bfdb-f348bf615140",
 *       "businessDisplayData": {
 *       "name": "Ticket Express"
 *     },
 *     "channels": [
 *       "CHAT",
 *       "EMAIL"
 *     ],
 *     "participant": {
 *       "contactId": "c5ef5c35-3b53-41c9-aeeb-214424e5f6e5"
 *     },
 *     "participantDisplayData": {
 *       "name": "Connor Dawson"
 *     }
 *   },
 *   "newConversation": true
 * }
 */


Get or create a conversation from a contact

/****************************
 * Backend code - events.js *
 ****************************/

import { sendMinimalMessage } from 'backend/inbox';

export function wixBlog_onPostLiked(event) {
  console.log(`New post liked with ID ${event.data.postId}`);  
  const anonymousVisitorId = event.data.anonymousVisitorId;
  sendMinimalMessage(anonymousVisitorId);
}

/*******************************
 * Backend code - inbox.web.js *
 *******************************/

import { Permissions, webMethod } from 'wix-web-module';
import { conversations, messages } from 'wix-inbox.v2';
import { elevate } from 'wix-auth';

export const sendMinimalMessage = webMethod(Permissions.Anyone, async (anonymousVisitorId) => {
  const message = {
    direction: 'PARTICIPANT_TO_BUSINESS',
    visibility: 'BUSINESS',
    content: {
      previewText: 'New Like',
      minimal: {
        text: 'New Like',
        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'
      }
    }
  }

  try {
    const conversationId = await getOrCreateConversationIdFromVisitor(anonymousVisitorId);

    const elevatedSendMessage = elevate(messages.sendMessage);
    const minimalMessage = await elevatedSendMessage(conversationId, message);
    console.log(`The message object returned is ${minimalMessage}`);

    return minimalMessage;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});

export const getOrCreateConversationIdFromVisitor = webMethod(Permissions.Anyone, async (anonymousVisitorId) => {
  const participantId = {
    anonymousVisitorId: anonymousVisitorId
  };

  try {
    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
    const conversationObject = await elevatedGetOrCreateConversation(participantId);

    return conversationObject.conversation._id;
  } catch (error) {
    console.error(error);
    //Handle the error
  }
});


This code detects a when a site visitor likes a blog post by registering the `onPostLiked` event listener in the `events.js` file. This event triggers an event object containing the `anonymousVisitorId`, which is  passed as an argument to `getOrCreateConversationIdFromVisitor`. The conversationId is returned and passed as a parameter to `sendMinimal`, which sends a minimal message to the site owner's inbox dashboard.

Get or create a conversation from a site visitor 

getOrCreateConversation

GetOrCreateConversationResponse

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'
```
  

inbox_conversations

ChannelType

Display name and avatar for the business.

businessDisplayData

ConversationDisplayData

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

Supported values: `"CHAT"`, `"EMAIL"`, `"SMS"`, `"FACEBOOK"`, `"INSTAGRAM"`, `"WHATSAPP"`.

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

conversation

Indicates whether the conversation previously exists or 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).

Setup

Permission Scopes

Permission Scopes