> 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`).
> - 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. 
     - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor. 
     - name: memberId | type: string | description: Member GUID. See the Members API for more information. 
 Return type: GetOrCreateConversationResponse
  - name: conversation | type: Conversation | description: Created or retrieved conversation. 
     - name: id | type: string | description: Conversation GUID. 
     - name: participant | type: IdentificationData | description: GUID of the visitor, contact, or member who is chatting with the business. 
        - ONE-OF: 
           - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor. 
           - name: memberId | type: string | description: Member GUID. See the Members API for more information. 
        - name: contactId | type: string | description: Contact GUID. See the Contacts API for more information. 
     - name: businessDisplayData | type: ConversationDisplayData | description: Display name and avatar for the business. 
        - name: name | type: string | description: Display name. 
        - name: imageUrl | type: string | description: Avatar image 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.ConversationsService.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. 
     - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor. 
     - name: memberId | type: string | description: Member GUID. See the Members API for more information. 
 Return type: PROMISE<GetOrCreateConversationResponse>
  - name: conversation | type: Conversation | description: Created or retrieved conversation. 
     - name: _id | type: string | description: Conversation GUID. 
     - name: participant | type: IdentificationData | description: GUID of the visitor, contact, or member who is chatting with the business. 
        - ONE-OF: 
           - name: anonymousVisitorId | type: string | description: GUID of an anonymous site visitor. 
           - name: memberId | type: string | description: Member GUID. See the Members API for more information. 
        - name: contactId | type: string | description: Contact GUID. See the Contacts API for more information. 
     - name: businessDisplayData | type: ConversationDisplayData | description: Display name and avatar for the business. 
        - name: name | type: string | description: Display name. 
        - name: imageUrl | type: string | description: Avatar image 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-hosted)
Self-hosted 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);
};
```

---