getOrCreateConversation( )

Developer Preview

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

Admin Method

This function requires elevated permissions to run. This function is not universal and runs only on the backend.

Syntax

function getOrCreateConversation(participantId: ParticipantId): Promise<GetOrCreateConversationResponse>

getOrCreateConversation Parameters

NAME

TYPE

DESCRIPTION

participantId

ParticipantId

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

Required for 3rd-party apps.

Returns

Return Type:

Promise<

GetOrCreateConversationResponse

NAME

TYPE

DESCRIPTION

conversation

Conversation

Created or retrieved conversation.

newConversation

boolean

Indicates whether the conversation was just created.

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

Was this helpful?

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

Copy Code

1import { conversations } from 'wix-inbox.v2';
2import { elevate } from 'wix-auth';
3
4/* Sample participantId value:
5 * {
6 *   memberId: 'b17c523c-6ec9-4b56-9d9d-123cc6978bdf'
7 * }
8 */
9
10export async function myGetOrCreateConversationFunction(participantId) { 
11  try {
12    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
13    const conversationObject = await elevatedGetOrCreateConversation(participantId);
14    const id = conversationObject.conversation._id;
15    const channels = conversationObject.conversation.channels;
16    const siteName = conversationObject.conversation.businessDisplayData.name;
17    
18    return conversationObject;
19  } catch (error) {
20    console.error(error);
21    // Handle the error
22  }
23}
24
25/* Promise resolves to:
26 * {
27 *   "conversation": {
28 *     "_id": "092d1135-99cf-3ca9-a0bf-378e1df4539b",
29 *     "businessDisplayData": {
30 *       "name": "Classic Cars"
31 *     },
32 *     "channels": [
33 *       "CHAT", 
34 *        EMAIL
35 *     ],
36 *     "participant": {
37 *       "memberId": "b17c523c-6ec9-4b56-9d9d-123cc6978bdf"
38 *     },
39 *      "participantDisplayData": {
40 *       "name": "alevine@email.com"
41 *   }
42 *   "newConversation": false
43 * }
44 */
45

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

Copy Code

1import { Permissions, webMethod } from 'wix-web-module';
2import { conversations } from 'wix-inbox.v2';
3import { elevate } from 'wix-auth';
4
5/* Sample participantId value:
6 * {
7 *   memberId: 'b17c523c-6ec9-4b56-9d9d-123cc6978bdf'
8 * }
9 */
10
11export const myGetOrCreateConversationFunction = webMethod(Permissions.Anyone, async (participantId) => {
12  
13  try {
14    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
15    const conversationObject = await elevatedGetOrCreateConversation(participantId);
16    const id = conversationObject.conversation._id;
17    const channels = conversationObject.conversation.channels;
18    const siteName = conversationObject.conversation.businessDisplayData.name;
19
20    return conversationObject;
21  } catch (error) {
22    console.error(error);
23    // Handle the error
24  }
25});
26
27/* Promise resolves to:
28 * {
29 *   "conversation": {
30 *     "_id": "092d1135-99cf-3ca9-a0bf-378e1df4539b",
31 *     "businessDisplayData": {
32 *       "name": "Classic Cars"
33 *     },
34 *     "channels": [
35 *       "CHAT", 
36 *        EMAIL
37 *     ],
38 *     "participant": {
39 *       "memberId": "b17c523c-6ec9-4b56-9d9d-123cc6978bdf"
40 *     },
41 *      "participantDisplayData": {
42 *       "name": "alevine@email.com"
43 *   }
44 *   "newConversation": false
45 * }
46 */
47

Get or create a new conversation with a member

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.

Copy Code

1/*******************************
2 * Backend code - inbox.web.js *
3 ******************************/
4
5import { Permissions, webMethod } from 'wix-web-module';
6import { conversations, messages } from 'wix-inbox.v2';
7import { currentMember } from 'wix-members-backend'
8import { elevate } from 'wix-auth';
9
10export const sendFormData = webMethod(Permissions.Anyone, async (formData) => {
11  const message = {
12    direction: 'PARTICIPANT_TO_BUSINESS',
13    visibility: 'BUSINESS',
14    content: {
15      previewText: 'New Contact',
16      form: {
17        title: 'New Contact',
18        description: 'New Contact Form',
19        fields: [
20          { 
21            name: 'First Name', 
22            value: formData.firstName
23          },
24          { 
25            name: 'Last Name', 
26            value: formData.lastName 
27          },
28          { 
29            name: 'email', 
30            value: formData.email 
31          },
32          { 
33            name: 'Wants Newsletter', 
34            value: formData.subscribeNewsletter.toString() 
35          }
36        ],
37      }
38    }
39  }
40  
41  try {
42    const conversationId = await getOrCreateConversationIdFromMember();
43
44    const elevatedSendMessage = elevate(messages.sendMessage);
45    const formMessage = await elevatedSendMessage(conversationId, message);
46
47    return formMessage;
48  } catch (error) {
49    console.error(error);
50    //Handle the error
51  }
52});
53
54export const getOrCreateConversationIdFromMember = webMethod(Permissions.Anyone, async () => {
55  const member = await currentMember.getMember();
56  const participantId = { 
57    memberId: member._id 
58  };
59  
60  try {
61    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
62    const conversationObject = await elevatedGetOrCreateConversation(participantId);
63    
64    return conversationObject.converation._id;
65  } catch (error) {
66    console.error(error);
67    //Handle the error
68  }
69});
70/*************
71 * Page code *
72 *************/
73
74import { sendFormData } from 'backend/inbox.web';
75
76$w.onReady(function () {
77  $w('#submitButton').onClick(async () => {
78    const firstName = $w('#firstName').value;
79    const lastName = $w('#lastName').value;
80    const email = $w('#email').value;
81    const subscribeNewsletter = $w('#subscribeNewsletter').checked;
82    const dataToInsert = {
83      firstName,
84      lastName,
85      email,
86      subscribeNewsletter
87    };
88
89    const formData = await sendFormData(dataToInsert);
90    console.log(`The form data is ${formData}`);
91  });
92});

Get or create a conversation with a contact

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.

Copy Code

1/****************************
2 * Backend code - events.js *
3 ****************************/
4
5import { sendThankYou } from 'backend/inbox';
6
7export function wixCrm_onContactCreated(event) {
8  const contactId = event.metadata.entityId;
9  sendThankYou(contactId);
10}
11
12/*******************************
13 * Backend code - inbox.web.js *
14 ******************************/
15
16import { Permissions, webMethod } from 'wix-web-module';
17import { conversations, messages } from 'wix-inbox.v2';
18import { elevate } from 'wix-auth';
19
20export const sendThankYou = webMethod(Permissions.Anyone, async (contactId) => {
21  const participantId = {
22    contactId: contactId
23  };
24  const message = {
25    direction: 'BUSINESS_TO_PARTICIPANT',
26    visibility: 'BUSINESS_AND_PARTICIPANT',
27    content: {
28      previewText: 'Thank You',
29      basic: {
30        items: [
31          { text: 'Thank you for your input' },
32        ]
33      }
34    },
35    sourceChannel: 'CHAT',
36    targetChannels: ['CHAT']
37  }
38  
39  try {
40    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
41    const conversationObject = await elevatedGetOrCreateConversation(participantId);
42    const conversationId = conversationObject.conversation._id;
43
44    const elevatedSendMessage = elevate(messages.sendMessage);
45    const thankYouMessage = await elevatedSendMessage(conversationId, message);
46
47    return thankYouMessage;
48  } catch (error) {
49    console.error(error);
50    //Handle the error
51  }
52});
53

Get or create a conversation with anonymousVisitorId

Copy Code

1import { Permissions, webMethod } from 'wix-web-module';
2import { conversations } from 'wix-inbox.v2';
3import { elevate } from 'wix-auth';
4
5/* Sample participantId value:
6 * {
7 *   anonymousVisitorId: 'af63e767-caeb-4435-bf8c-f14ebd413060'
8 * }
9 */
10
11export const getConversationFromVisitor = webMethod(Permissions.Anyone, async (participantId) => {
12  try {
13    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation)
14    const conversationObject = await elevatedGetOrCreateConversation(participantId);
15    const id = conversationObject.conversation._id;
16    const firstChannel = conversationObject.conversation.channels[0];
17
18    return conversationObject;
19  } catch (error) {
20    console.error(error);
21    //Handle the error
22  }
23});
24
25/* Promise resolves to:
26 * {
27 *   "conversation": {
28 *     "_id": "c4999cbd-33ea-37cb-a374-75600f409d0b",
29 *     "businessDisplayData": {
30 *       "name": "Peak Fitness"
31 *     },
32 *     "channels": [
33 *       "CHAT"
34 *     ],
35 *     "participant": {
36 *       "anonymousVisitorId": "5dc5855b-0e34-495b-9762-3a9f591baa37"
37 *     },
38 *     "participantDisplayData": {
39 *       "name": "Visitor #8145",
40 *       "imageUrl": "https://static.parastorage.com/services/engage-web/1.6076.0/assets/visitor-avatars-faces/Avatar1Orange.png"
41 *     }
42 *   },
43 *   "newConversation": false
44 * }
45 */
46

Get or create a conversation from a contact

Copy Code

1import { Permissions, webMethod } from 'wix-web-module';
2import { conversations } from 'wix-inbox.v2';
3import { elevate } from 'wix-auth';
4
5/* Sample participantId value:
6 * {
7 *   contactId: 'c5ef5c35-3b53-41c9-aeeb-214424e5f6e5'
8 * }
9 */
10
11export const myGetOrCreateConversationFunction = webMethod(Permissions.Anyone, async (participantId) => {
12  
13  try {
14    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
15    const conversationObject = await conversations.getOrCreateConversation(participantId);
16    const id = conversationObject.conversation._id;
17    const channels = conversationObject.conversation.channels;
18    const siteName = conversationObject.conversation.businessDisplayData.name;
19
20    return conversationObject;
21  } catch (error) {
22    console.error(error);
23    //Handle the error
24  }
25});
26
27/* Promise resolves to:
28 * {
29 *   "conversation": {
30 *     "_id": "7d313780-d237-3d5e-bfdb-f348bf615140",
31 *       "businessDisplayData": {
32 *       "name": "Ticket Express"
33 *     },
34 *     "channels": [
35 *       "CHAT",
36 *       "EMAIL"
37 *     ],
38 *     "participant": {
39 *       "contactId": "c5ef5c35-3b53-41c9-aeeb-214424e5f6e5"
40 *     },
41 *     "participantDisplayData": {
42 *       "name": "Connor Dawson"
43 *     }
44 *   },
45 *   "newConversation": true
46 * }
47 */
48

Get or create a conversation from a site visitor

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.

Copy Code

1/****************************
2 * Backend code - events.js *
3 ****************************/
4
5import { sendMinimalMessage } from 'backend/inbox';
6
7export function wixBlog_onPostLiked(event) {
8  console.log(`New post liked with ID ${event.data.postId}`);  
9  const anonymousVisitorId = event.data.anonymousVisitorId;
10  sendMinimalMessage(anonymousVisitorId);
11}
12
13/****************************
14 * Backend code - inbox.web.js *
15 ****************************/
16
17import { Permissions, webMethod } from 'wix-web-module';
18import { conversations, messages } from 'wix-inbox.v2';
19import { elevate } from 'wix-auth';
20
21export const sendMinimalMessage = webMethod(Permissions.Anyone, async (anonymousVisitorId) => {
22  const message = {
23    direction: 'PARTICIPANT_TO_BUSINESS',
24    visibility: 'BUSINESS',
25    content: {
26      previewText: 'New Like',
27      minimal: {
28        text: 'New Like',
29        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'
30      }
31    }
32  }
33
34  try {
35    const conversationId = await getOrCreateConversationIdFromVisitor(anonymousVisitorId);
36
37    const elevatedSendMessage = elevate(messages.sendMessage);
38    const minimalMessage = await elevatedSendMessage(conversationId, message);
39    console.log(`The message object returned is ${minimalMessage}`);
40
41    return minimalMessage;
42  } catch (error) {
43    console.error(error);
44    //Handle the error
45  }
46});
47
48export const getOrCreateConversationIdFromVisitor = webMethod(Permissions.Anyone, async (anonymousVisitorId) => {
49  const participantId = {
50    anonymousVisitorId: anonymousVisitorId
51  };
52
53  try {
54    const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
55    const conversationObject = await elevatedGetOrCreateConversation(participantId);
56
57    return conversationObject.conversation._id;
58  } catch (error) {
59    console.error(error);
60    //Handle the error
61  }
62});
63