> 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/messages.md).

# Messages

### Create a message

A text-only message, or a message created from a message template (the template can have video, audio, and/or text).

## Create a text-only message or template-based message

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

#### Query Parameters

| Name                                               | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| -------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conversation\_id<mark style="color:red;">\*</mark> | integer | Pass the ID of the Conversation that this message will be added to.                                                                                                                                                                                                                                                                                                                                                                                                 |
| text<mark style="color:red;">\*</mark>             | string  | Pass the text for the content of the message.  It can include HTML.  If a full URL is included in the text, it will be automatically converted to a link.                                                                                                                                                                                                                                                                                                           |
| message\_template\_id                              | integer | <p>Pass the ID of a message template to use as the content for this message.  <br><br>If the message template contains text, then this text would override the value you pass along with the text parameter.<br><br>If the message template does not contain text, then any text you pass in the query parameter will be added to the message underneath the media player.<br><br>The message will be attributed to the user who created this message template.</p> |
| user\_email                                        | String  | <p>Email address of the user that this message should be attributed to.  This user with this email address must be an owner or team member in the account.<br><br>If blank, then the message will be posted anonymously.</p>                                                                                                                                                                                                                                        |
| internal                                           | boolean | If `true`, then this message will be posted as an "internal" message, which is only visible to team members in the account.  Internal messages are not visible to guests and non-logged-in users.                                                                                                                                                                                                                                                                   |

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

```javascript
{
    "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": "<p>New Text Message</p><p>This is the second paragraph with <strong>bold text</strong>.</p><p>This URL will automatically link: https://google.com</p>",
    "message_template": null,
    "message_created_time": "2022-02-01 17:21:37.455575",
    "message_credated_time_nice": "February 2nd, 2022 05:21PM UTC",
}
```

{% endtab %}

{% tab title="400: Bad Request When a conversation ID is missing." %}

```javascript
{
    "error": "Required parameter conversation_id is missing"
}
```

{% endtab %}

{% tab title="404: Not Found When a conversation ID is present but a conversation by that ID doesn't exist." %}

```javascript
{
    "error": "Record not found"
}
```

{% endtab %}

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

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

{% endtab %}
{% endtabs %}

### Get messages

## Get messages

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

#### Query Parameters

| Name               | Type       | Description                                                                                                                                                                                       |
| ------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conversation\_slug | String     | If the `conversation_slug` is passed, then only messages from this conversation will be returned.  If `conversation_slug` is not present, then messages from all conversationsn will be returned. |
| page               | integer    | A maximum of 50 messages will be returned starting from th most recently created message. To retrieve messages further back than 50, pass the page number.                                        |
| date\_time         | yyyy-mm-dd | If `date_time` is passed, then only messages that were created after this date will be returned.                                                                                                  |
| email              | String     | If `email` is passed, only messages authored by the user who has this email will be returned.                                                                                                     |

{% tabs %}
{% tab title="200: OK `download_media_url` will initially return a media file in `webm` format.  Once the transcoding process finishes (typically a few moments up to 10 minutes after message creation), `download_media_url` will return the mp4 video or mp3 if it was an audio-only message." %}

```javascript
{
    "messages": [
        {
            "id": 1184,
            "conversation_id": 512,
            "message_type": "screen",
            "recorded_duration_seconds": 4,
            "author": {
                "id": 50,
                "email": "user@example.com",
                "name": "User"
            },
            "message_url": "https://awesomecompany.clarityflow.com/c/14c8ec4e530e129b6fe73ca81#message-1184",
            "embed_message_url": "https://awesomecompany.clarityflow.com/embeds/messages/Your_account/1184&show_author=true' id='zm-iframe' style='width:100%;min-height:400px;'></iframe><script src='http://localhost:3000/scripts/embed.js' async></script>",
            "download_media_url": "https://zipmessage.s3.amazonaws.com/14c8ec4e530e129b6fe73ca81?response-content-disposition=attachment%3B%20filename%3D%22recording.webm%22%3B%20filename%2A%3DUTF-8%27%27recording.webm&response-content-type=video%2Fwebm&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3ARUPDB3HFYUPVYV%2F20220103%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220103T113838Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=4ac76944b0efdf9d4c91b7cb313318f81ce094a13a8e695ca3577d43bef6d739",
            "text": "",
            "message_template": null,
            "message_created_time": "2022-02-01 17:21:37.455575",
            "message_credated_time_nice": "February 2nd, 2022 05:21PM UTC"
        },
        {
            "id": 1183,
            "conversation_id": 512,
            "message_type": "screen",
            "recorded_duration_seconds": 7,
            "author": {
                "id": 50,
                "email": "user@example.com",
                "name": "User"
            },
            "message_url": "https://awesomecompany.clarityflow.com/c/14c8ec4e530e129b6fe73ca81#message-1183",
            "embed_message_url": "https://awesomecompany.clarityflow.com/embeds/messages/Your_account/1183",
            "download_media_url": "https://zipmessage.s3.amazonaws.com/3nn3vc5mhcsvq58fciz0d7usamyd?response-content-disposition=attachment%3B%20filename%3D%22recording.webm%22%3B%20filename%2A%3DUTF-8%27%27recording.webm&response-content-type=video%2Fwebm&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3ARUPDB3HFYUPVYV%2F20220103%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220103T113838Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=7b32fc5fbf32d642808afa8c6fa20b63af30e639b84a9df0c722e78d01c65899",
            "text": "",
            "message_template": null,
            "message_created_time": "2022-02-01 17:21:37.455575",
            "message_credated_time_nice": "February 2nd, 2022 05:21PM UTC"
        }
    ],
    "pages": 1
}
```

{% endtab %}

{% tab title="404: Not Found If a `conversation_slug` that does not exist is passed, this error will be returned." %}

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

{% endtab %}
{% endtabs %}