> To build or manage a Wix site with an AI agent, follow https://www.wix.com/headless/skill.md
> It builds a new Wix site or puts your own site online, from a prompt, and keeps changing it afterwards. The pages are code in any web technology, and Wix runs the backend.
> It works through the Wix plugin (the Wix MCP and the Wix skills), the Wix CLI or no Wix login, and puts the site live on Wix hosting or on another host.
> Business features include a store, bookings, events and tickets, a restaurant, a blog, forms, members and many more.
> Read the Wix skills online at https://www.wix.com/skills
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# GetOrCreateConversation

# Package: inbox

# Namespace: ConversationsService

# Method link: https://dev.wix.com/docs/api-reference/crm/communication/inbox/conversations/get-or-create-conversation.md

## Permission Scopes:
Manage Inbox Messages: SCOPE.DC-INBOX.MANAGE-MSGS

## Introduction

Retrieves a conversation by the specified visitor, contact, or member ID. If the conversation doesn't exist for the specified visitor, contact, or member, the method creates a new conversation.

---

## REST API

### Schema

```
 Method: getOrCreateConversation
 Description: Retrieves a conversation by the specified visitor, contact, or member GUID. If the conversation doesn't exist for the specified visitor, contact, or member, the method creates a new conversation.
 URL: https://www.wixapis.com/inbox/v2/conversations
 Method: POST
 Method parameters:
   param name: participantId | type: ParticipantId    
    - ONE-OF: 
     - name: contactId | type: string | description: Contact GUID. See the Contacts API for more information.  | validation: format GUID
     - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor.  | validation: format GUID
     - name: memberId | type: string | description: Member GUID. See the Members API for more information.  | validation: format GUID
 Return type: GetOrCreateConversationResponse
  - name: conversation | type: Conversation | description: Created or retrieved conversation.  
     - name: id | type: string | description: Conversation GUID.  | read-only: true | validation: format GUID
     - name: participant | type: IdentificationData | description: GUID of the visitor, contact, or member who is chatting with the business.  | read-only: true 
        - ONE-OF: 
           - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor.  | validation: format GUID
           - name: memberId | type: string | description: Member GUID. See the Members API for more information.  | validation: format GUID
        - name: contactId | type: string | description: Contact GUID. See the Contacts API for more information.  | read-only: true | validation: format GUID
     - name: businessDisplayData | type: ConversationDisplayData | description: Display name and avatar for the business.  
        - name: name | type: string | description: Display name.  | read-only: true 
        - name: imageUrl | type: string | description: Avatar image URL.  | read-only: true | validation: format WEB_URL
     - name: participantDisplayData | type: ConversationDisplayData | description: Display name and avatar for the visitor, contact, or member.  
  - name: newConversation | type: boolean | description: Indicates whether the conversation previously exists or was just created.  If `true`, the conversation was just created. If `false`, the conversation already existed.  


```

### Examples

### GetOrCreateConversation
```curl
~~~cURL
curl -X POST \
'https://www.wixapis.com/inbox/v2/conversations' \
-H 'Authorization: <AUTH>' \
-d '{
  "participantId": {
    "anonymousVisitorId": "40096143-3643-4cc1-8329-30a7fc2c595e"
  }
}'
~~~
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.inbox.conversations.getOrCreateConversation(participantId)
 Description: Retrieves a conversation by the specified visitor, contact, or member GUID. If the conversation doesn't exist for the specified visitor, contact, or member, the method creates a new conversation.
 Method parameters:
   param name: participantId | type: ParticipantId   | required: true 
    - ONE-OF: - required: true
     - name: contactId | type: string | description: Contact GUID. See the Contacts API for more information.  | validation: format GUID
     - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor.  | validation: format GUID
     - name: memberId | type: string | description: Member GUID. See the Members API for more information.  | validation: format GUID
 Return type: PROMISE<GetOrCreateConversationResponse>
  - name: conversation | type: Conversation | description: Created or retrieved conversation.  
     - name: _id | type: string | description: Conversation GUID.  | read-only: true | validation: format GUID
     - name: participant | type: IdentificationData | description: GUID of the visitor, contact, or member who is chatting with the business.  | read-only: true 
        - ONE-OF: 
           - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor.  | validation: format GUID
           - name: memberId | type: string | description: Member GUID. See the Members API for more information.  | validation: format GUID
        - name: contactId | type: string | description: Contact GUID. See the Contacts API for more information.  | read-only: true | validation: format GUID
     - name: businessDisplayData | type: ConversationDisplayData | description: Display name and avatar for the business.  
        - name: name | type: string | description: Display name.  | read-only: true 
        - name: imageUrl | type: string | description: Avatar image URL.  | read-only: true | validation: format WEB_URL
     - name: participantDisplayData | type: ConversationDisplayData | description: Display name and avatar for the visitor, contact, or member.  
  - name: newConversation | type: boolean | description: Indicates whether the conversation previously exists or was just created.  If `true`, the conversation was just created. If `false`, the conversation already existed.  


```

### Examples

### Get or create a conversation from a member (with elevated permissions)
```javascript
import { conversations } from '@wix/inbox';
import { auth } from '@wix/essentials';

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

export async function myGetOrCreateConversationFunction(participantId) { 
  try {
    const elevatedGetOrCreateConversation = auth.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
```javascript
import { conversations } from '@wix/inbox';

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

export async function myGetOrCreateConversationFunction(participantId) { 
  try {
    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": "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 contact (with elevated permissions)
```javascript
import { conversations } from '@wix/inbox';
import { auth } from '@wix/essentials';

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

export async function myGetOrCreateConversationFunction(participantId) {
  
  try {
    const elevatedGetOrCreateConversation = auth.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
```javascript
import { conversations } from '@wix/inbox';

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

export async function myGetOrCreateConversationFunction(participantId) {
  
  try {
    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 with anonymousVisitorId (with elevated permissions)
```javascript
import { conversations } from '@wix/inbox';
import { auth } from '@wix/essentials';

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

export async function getConversationFromVisitor(participantId) {
  try {
    const elevatedGetOrCreateConversation = auth.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
```javascript
import { conversations } from '@wix/inbox';

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

export async function getConversationFromVisitor(participantId) {
  try {
    const conversationObject = await conversations.getOrCreateConversation(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
 * }
 */
```

### getOrCreateConversation (self-managed)
Self-managed SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { conversations } from '@wix/inbox';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { conversations },
  // Include the auth strategy and host as relevant
});


async function getOrCreateConversation(participantId) {
  const response = await myWixClient.conversations.getOrCreateConversation(participantId);
};
```

---