> For the complete documentation index, see [llms.txt](https://api.clarityflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.clarityflow.com/api-reference/conversations.md).

# Conversations

## Creating a new conversation

## Create conversation.

<mark style="color:green;">`POST`</mark> `https://app.clarityflow.com/api/v1/conversations/create_conversation`

Creates a new conversation.

#### Request Body

| Name                       | Type    | Description                                                                                                                                                                                                                                                                                    |
| -------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title                      | string  | If title is passed, the new conversation will have the passed value as title.  If title is not passed, then the new conversation will use the default naming convention for new conversatons based in the account settings.                                                                    |
| slug                       | string  | If slug is set, new conversation will be have the passed value as slug.  This cannot contain spaces or special characters except for `_` or `-`.                                                                                                                                               |
| anyone\_can\_post          | boolean | If `true` then the conversation will be visible to anyone who can access it's URL.  If `false` then it will be set to "Private" and only accessible by logged-in users who are members of this conversation.  If not set, it will default to whatever this setting is in the account settings. |
| allow\_anonymous\_messages | boolean | If `true` then when people submit their replies, they will have the option to post their reply messages anonymously.  If `false`, then they will be required to register with their name and email or sign into Clarityflow in order to submit their reply to this conversation.               |
| allow\_search\_engines     | boolean | If `true` then this conversation can be indexed by search engines.  If `false` then robots.txt will instruct search engines not to index this conversation URL.  If not set, then this setting defaults to what this is set to in account settings.                                            |
| primary\_intake\_page      | boolean | <p>If <code>true</code>, it will be as if this conversation was created by submitting the form on your account's primary intake page.<br><br>This is useful if you want to automatically apply the workflow that is set on your primary intake page to the conversation. </p>                  |
| intake\_page\_id           | integer | <p>If set to the ID of a secondary intake page, it will be as if this conversation was created by submitting the form on your that intake page.<br><br>This is useful if you want to automatically apply the workflow that is set on your intake page to the conversation. </p>                |

{% tabs %}
{% tab title="200 Conversation successfully created" %}

```javascript
{
    "id": 1,
    "title": "Test conversation",
    "slug": "096a594dd11759d1f6876d842",
    "public": true,
    "via_primary_intake_page": false,
    "intake_page_id": null,
    "conversation_url": "https://awesomecompany.clarityflow.com/c/096a594dd11759d1f6876d842",
    "conversation_embed_url": "https://awesomecompany.clarityflow.com/embeds/conversations/Your_account/096a594dd11759d1f6876d842",
    "anyone_can_post": true,
    "allow_anonymous_messages": true,
    "allow_search_engines": false,
    "tags": [],
    "users": [
        {
            "id": 1,
            "email": "user@example.com",
            "name": "User"
        }
    ],
    "messages": []
}
```

{% endtab %}

{% tab title="422: Unprocessable Entity Permission denied" %}
The `slug` must validate by containing no spaces or special characters and must not already be in use by another conversation in this account.
{% endtab %}

{% tab title="401: Unauthorized Authentication Failed" %}

```javascript
{
    "error": "Authentication Failed"
}
```

{% endtab %}
{% endtabs %}

## Get a conversation(s)

## Get a single conversation

<mark style="color:blue;">`GET`</mark> `https://app.clarityflow.com/api/v1/conversations/get_conversation`

Retrieves a single conversation the account.  If neither `title` nor `slug` are passed, then this will return the most recently created conversation in the account.

#### Query Parameters

| Name  | Type   | Description                                                                                                                                                                                                                                                                                     |
| ----- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title | String | <p>If passed, the most recently created conversation with a title that exactly matches this string (case insensitive) will be returned.<br><br>If not passed, or if the title doesn't match any conversatoins, then the most recently created conversation in the account will be returned.</p> |
| slug  | String | <p>If passed, the most recently created conversation with a slug that exactly matches this string (case insensitive) will be returned.<br><br>If not passed, or if the title doesn't match any conversatoins, then the most recently created conversation in the account will be returned.</p>  |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "id": 547,
    "title": "January 3rd, 2022 Conversation",
    "slug": "77a41d5a8e71d5f64998348f6",
    "public": false,
    "via_primary_intake_page": false,
    "intake_page_id": null,
    "conversation_url": "https://awesomecompany.clarityflow.com/c/77a41d5a8e71d5f64998348f6",
    "conversation_embed_url": "https://awesomecompany.clarityflow.com/embeds/conversations/Your_account/77a41d5a8e71d5f64998348f6",
    "anyone_can_post": false,
    "allow_anonymous_messages": false,
    "allow_search_engines": false,
    "conversation_created_time": "2022-02-01 17:21:37.455575",
    "conversation_credated_time_nice": "February 2nd, 2022 05:21PM UTC",
    "tags": [],
    "users": [
        {
            "id": 50,
            "email": "user@example.com",
            "name": "User"
        }
    ],
    "messages": [],
    "workflow": {}
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    "error": "Authentication Failed"
}
```

{% endtab %}

{% tab title="404: Not Found " %}

```javascript
{
    "error": "Sorry! No conversations found."
}
```

{% endtab %}
{% endtabs %}

## Get conversations

<mark style="color:blue;">`GET`</mark> `https://app.clarityflow.com/api/v1/conversations/get_conversations`

Returns an array of conversations from the account.

#### Query Parameters

| Name | Type    | Description                                                                                                                                                               |
| ---- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page | integer | A maximum of 50 conversations will be returned starting from th most recently created conversation. To retrieve conversations further back than 50, pass the page number. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "conversations": [
        {
            "id": 544,
            "title": "Test conversation",
            "slug": "096a594dd11759d1f6876d842",
            "public": true,
            "via_primary_intake_page": false,
            "intake_page_id": null,
            "conversation_url": "https://awesomecompany.clarityflow.com/c/096a594dd11759d1f6876d842",
            "conversation_embed_url": "https://awesomecompany.clarityflow.com/embeds/conversations/oz3jqo57/096a594dd11759d1f6876d842",
            "anyone_can_post": true,
            "allow_anonymous_messages": true,
            "allow_search_engines": false,
            "tags": [],
            "users": [
                {
                    "id": 50,
                    "email": "user@example.com",
                    "name": "User"
                }
            ],
            "messages": [
                {
                    "id": 1206,
                    "conversation_id": 544,
                    "message_type": "text",
                    "recorded_duration_seconds": 0,
                    "author": {
                        "anonymous": true
                    },
                    "message_url": "https://awesomecompany.clarityflow.com/c/096a594dd11759d1f6876d842#message-1206",
                    "embed_message_url": "https://awesomecompany.clarityflow.com/embeds/messages/Your_account/1206&show_author=true",
                    "download_media_url": null,
                    "text": "Create new text message 1"
                },
                {
                    "id": 1207,
                    "conversation_id": 544,
                    "message_type": "text",
                    "recorded_duration_seconds": 0,
                    "author": {
                        "anonymous": true
                    },
                    "message_url": "https://awesomecompany.clarityflow.com/c/096a594dd11759d1f6876d842#message-1207",
                    "embed_message_url": "https://awesomecompany.clarityflow.com/embeds/messages/Your_account/1207&show_author=true",
                    "download_media_url": null,
                    "text": "Create new text message 2"
                }
            ],
            "workflow": {}
        },
        {
            "id": 545,
            "title": "New conversation",
            "slug": "ecf2c8ba4b95724ca54cea439",
            "public": true,
            "via_primary_intake_page": false,
            "intake_page_id": null,
            "conversation_url": "https://awesomecompany.clarityflow.com/c/ecf2c8ba4b95724ca54cea439",
            "conversation_embed_url": "https://awesomecompany.clarityflow.com/embeds/conversations/Your_account/ecf2c8ba4b95724ca54cea439",
            "anyone_can_post": true,
            "allow_anonymous_messages": true,
            "allow_search_engines": false,
            "tags": [],
            "users": [
                {
                    "id": 50,
                    "email": "user@example.com",
                    "name": "User"
                }
            ],
            "messages": [],
            "workflow": {}
        }
  ]
}
```

{% endtab %}

{% tab title="404: Not Found " %}

```javascript
{
    "error": "Sorry! No conversations found."
}
```

{% endtab %}

{% tab title="401: Unauthorized " %}

```javascript
{
    "error": "Authentication Failed"
}
```

{% endtab %}
{% endtabs %}