Conversations

Conversations in Clarityflow can contain one or several messages exchanged between multiple people.

Creating a new conversation

Create conversation.

POST 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	If true, it will be as if this conversation was created by submitting the form on your account's primary intake page. This is useful if you want to automatically apply the workflow that is set on your primary intake page to the conversation.
intake_page_id	integer	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. This is useful if you want to automatically apply the workflow that is set on your intake page to the conversation.

200 Conversation successfully created

{
    "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": "[e-mail]",
            "name": "User"
        }
    ],
    "messages": []
}

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.

401: Unauthorized Authentication Failed

{
    "error": "Authentication Failed"
}

Get a conversation(s)

Get a single conversation

GET 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	If passed, the most recently created conversation with a title that exactly matches this string (case insensitive) will be returned. If not passed, or if the title doesn't match any conversatoins, then the most recently created conversation in the account will be returned.
slug	String	If passed, the most recently created conversation with a slug that exactly matches this string (case insensitive) will be returned. If not passed, or if the title doesn't match any conversatoins, then the most recently created conversation in the account will be returned.

200: OK

{
    "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": "[e-mail]",
            "name": "User"
        }
    ],
    "messages": [],
    "workflow": {}
}

401: Unauthorized

{
    "error": "Authentication Failed"
}

404: Not Found

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

Get conversations

GET 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.

200: OK

{
    "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": "[e-mail]",
                    "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": "[e-mail]",
                    "name": "User"
                }
            ],
            "messages": [],
            "workflow": {}
        }
  ]
}

404: Not Found

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

401: Unauthorized

{
    "error": "Authentication Failed"
}