Search.../

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

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
12 try {
13 const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
14 const conversationObject = await elevatedGetOrCreateConversation(participantId);
15 const id = conversationObject.conversation._id;
16 const channels = conversationObject.conversation.channels;
17 const siteName = conversationObject.conversation.businessDisplayData.name;
18
19 return conversationObject;
20 } catch (error) {
21 console.error(error);
22 // Handle the error
23 }
24}
25
26/* Promise resolves to:
27 * {
28 * "conversation": {
29 * "_id": "092d1135-99cf-3ca9-a0bf-378e1df4539b",
30 * "businessDisplayData": {
31 * "name": "Classic Cars"
32 * },
33 * "channels": [
34 * "CHAT",
35 * EMAIL
36 * ],
37 * "participant": {
38 * "memberId": "b17c523c-6ec9-4b56-9d9d-123cc6978bdf"
39 * },
40 * "participantDisplayData": {
41 * "name": "alevine@email.com"
42 * }
43 * "newConversation": false
44 * }
45 */
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.jsw *
14 ****************************/
15
16import { conversations, messages } from 'wix-inbox.v2';
17import { elevate } from 'wix-auth';
18
19export async function sendThankYou(contactId) {
20 const participantId = {
21 contactId: contactId
22 };
23 const message = {
24 direction: 'BUSINESS_TO_PARTICIPANT',
25 visibility: 'BUSINESS_AND_PARTICIPANT',
26 content: {
27 previewText: 'Thank You',
28 basic: {
29 items: [
30 { text: 'Thank you for your input' },
31 ]
32 }
33 },
34 sourceChannel: 'CHAT',
35 targetChannels: ['CHAT']
36 }
37
38 try {
39 const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
40 const conversationObject = await elevatedGetOrCreateConversation(participantId);
41 const conversationId = conversationObject.converation._id;
42
43 const elevatedSendMessage = elevate(messages.sendMessage);
44 const thankYouMessage = await elevatedSendMessage(conversationId, message);
45
46 return thankYouMessage;
47 } catch (error) {
48 console.error(error);
49 //Handle the error
50 }
51}
Get or create a conversation with anonymousVisitorId

Copy Code
1import { conversations } from 'wix-inbox.v2';
2import { elevate } from 'wix-auth';
3
4/* Sample participantId value:
5 * {
6 * anonymousVisitorId: 'af63e767-caeb-4435-bf8c-f14ebd413060'
7 * }
8 */
9
10export async function getConversationFromVisitor(participantId) {
11
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 */
Get or create a conversation from a contact

Copy Code
1import { conversations } from 'wix-inbox.v2';
2import { elevate } from 'wix-auth';
3
4/* Sample participantId value:
5 * {
6 * contactId: 'c5ef5c35-3b53-41c9-aeeb-214424e5f6e5'
7 * }
8 */
9
10export async function myGetOrCreateConversationFunction(participantId) {
11
12 try {
13 const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
14 const conversationObject = await conversations.getOrCreateConversation(participantId);
15 const id = conversationObject.conversation._id;
16 const channels = conversationObject.conversation.channels;
17 const siteName = conversationObject.conversation.businessDisplayData.name;
18
19 return conversationObject;
20 } catch (error) {
21 console.error(error);
22 //Handle the error
23 }
24}
25
26/* Promise resolves to:
27 * {
28 * "conversation": {
29 * "_id": "7d313780-d237-3d5e-bfdb-f348bf615140",
30 * "businessDisplayData": {
31 * "name": "Ticket Express"
32 * },
33 * "channels": [
34 * "CHAT",
35 * "EMAIL"
36 * ],
37 * "participant": {
38 * "contactId": "c5ef5c35-3b53-41c9-aeeb-214424e5f6e5"
39 * },
40 * "participantDisplayData": {
41 * "name": "Connor Dawson"
42 * }
43 * },
44 * "newConversation": true
45 * }
46 */
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.jsw *
15 ****************************/
16
17import { conversations, messages } from 'wix-inbox.v2';
18import { elevate } from 'wix-auth';
19
20export async function sendMinimalMessage(anonymousVisitorId) {
21 const message = {
22 direction: 'PARTICIPANT_TO_BUSINESS',
23 visibility: 'BUSINESS',
24 content: {
25 previewText: 'New Like',
26 minimal: {
27 text: 'New Like',
28 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'
29 }
30 }
31 }
32
33 try {
34 const conversationId = await getOrCreateConversationIdFromVisitor(anonymousVisitorId);
35
36 const elevatedSendMessage = elevate(messages.sendMessage);
37 const minimalMessage = await elevatedSendMessage(conversationId, message);
38 console.log(`The message object returned is ${minimalMessage}`);
39
40 return minimalMessage;
41 } catch (error) {
42 console.error(error);
43 //Handle the error
44 }
45}
46
47export async function getOrCreateConversationIdFromVisitor(anonymousVisitorId) {
48 const participantId = {
49 anonymousVisitorId: anonymousVisitorId
50 };
51
52 try {
53 const elevatedGetOrCreateConversation = elevate(conversations.getOrCreateConversation);
54 const conversationObject = await elevatedGetOrCreateConversation(participantId);
55
56 return conversationObject.conversation._id;
57 } catch (error) {
58 console.error(error);
59 //Handle the error
60 }
61}