Webhook Events

These are the request bodies for each event that can trigger webhooks:

Conversation created

This event occurs when a new Clarityflow (formerly known as ZipMessage) conversation is created. Conversations can be created in any of the following ways:

  • You or a teammate clicks "Create Conversation" in your Clarityflow account interface.

  • A guest submits a message via any of your intake page(s). This generates a new Conversation.

  • A Conversation can be created via Zapier.

  • A Conversation can be created via the API.

  • A Conversation can be creating by using our browser extensions.

Here is an example request body:

{
  "type": "conversation_created",
  "id": "f6689254-9d5f-43b0-9de1-125a6ca639f1",
  "occurred_at": "2022-04-01T14:23:59.799+00:00",
  "payload": {
    "conversation": {
      "id": 268,
      "created_at": "2022-04-01 14:23:1648823039",
      "title": "April 1st, 2022 Conversation",
      "slug": "april-1st-2022-conversation1",
      "url": "http://awesomecompany.clarityflow.com/c/april-1st-2022-conversation1",
      "embed_url": "http://awesomecompany.clarityflow.com/embeds/conversations/awesomecompany/april-1st-2022-conversation1",
      "public": true,
      "anyone_can_post": true,
      "allow_anonymous_messages": true,
      "allow_search_engines": false,
      "enable_registration_prompt": true,
      "subscriber_emails": [],
      "messages": [],
      "workflow": {}
    }
  }
}

Message created

Messages reside in Conversations. A Message is created when someone has posted a message in a conversation. A Message can have video, audio, and/or text content. A message may be sent by an identified person or sent anonymously.

Messages are created in any of these ways:

  • A user views a conversation then creates and posts a message in it.

  • A user submits a message via your intake page(s).

  • A text message can be created via Zapier.

  • A text message can be created via the API.

Here is an example request body:

{
  "type": "message_created",
  "id": "c6ec4301-8d97-4c53-8dff-06947ff750ca",
  "occurred_at": "2022-04-01T14:24:14.196+00:00",
  "payload": {
    "message": {
      "id": 330,
      "conversation_title": "April 1st, 2022 Conversation",
      "message_type": "text",
      "recorded_duration_seconds": null,
      "message_url": "http://awesomecompany.clarityflow.com/c/april-1st-2022-conversation1#message-330",
      "message_embed_url": "http://awesomecompany.clarityflow.com/embeds/messages/awesomecompany/330?conversation_slug=april-1st-2022-conversation1",
      "text": "<div class=\"trix-content\">\n  <div class=\"trix-content\">\n  <div class=\"trix-content\">\n  <div>asdf</div>\n</div>\n</div>\n</div>",
      "message_created_time": "2022-04-01 14:24:1648823053",
      "author": {
        "first_name": "User",
        "last_name": "Casel",
        "full_name": "User Casel",
        "email": "user@example.com"
      },
      "download_media_url": "https://zipmessage-production-input.s3.amazonaws.com/68u6m2jb5ydijz5oa4tk0ivm07hx?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%2F20220701%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220701T201029Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=b8595e540eaf27dcd8c6e11c78d2e5bf9907e0e2932c6851f02a95e6aea9c4f0",
      "access_media_file": "https://zipmessage.com/330/download_media",
      "workflow": {}
    }
  }
}

Message played

This event fires when a message's media (video or audio) player has been played back by someone. The person playing a message can be an identified logged-in user or an anonymous viewer.

This webhook follows the same logic as notifications for when a message is played. Some notes:

  • The webhook fires once per user playing a message.

  • The webhook fires once per user's session.

  • The webhook only fires if the message being played has an author (the message wasn't posted anonymously).

Examples:

  • If a logged-in user plays a message for the first time, this will fire the webhook. But if that same user plays the same message a 2nd time, it will not send an additional webhook for the 2nd play.

  • A non-logged-in visitor plays a message once, which fires the webhook. During the same browser session, this user presses play on the same message a 2nd time. This 2nd play does not fire an additional webhook.

Here is an example request body:

{
  "type": "message_played",
  "id": "abfe656b-cb51-4540-af32-a8e8b954221b",
  "occurred_at": "2022-04-01T14:25:48.585+00:00",
  "payload": {
    "message": {
      "id": 283,
      "conversation_title": "Conversation with emma casel",
      "message_type": "screencamera",
      "recorded_duration_seconds": 1,
      "message_url": "http://awesomecompany.clarityflow.com/c/conversation-with-emma-casel#message-283",
      "message_embed_url": "http://awesomecompany.clarityflow.com/embeds/messages/awesomecompany/283?conversation_slug=conversation-with-emma-casel",
      "text": "",
      "message_created_time": "2022-01-08 18:02:1641664979",
      "author": {
        "first_name": "User",
        "last_name": "Casel",
        "full_name": "User Casel",
        "email": "user@example.com"
      },
      "download_media_url": "https://zipmessage-production-input.s3.amazonaws.com/68u6m2jb5ydijz5oa4tk0ivm07hx?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%2F20220701%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220701T201029Z&X-Amz-Expires=300&X-Amz-SignedHeaders=host&X-Amz-Signature=b8595e540eaf27dcd8c6e11c78d2e5bf9907e0e2932c6851f02a95e6aea9c4f0",
      "access_media_file": "https://zipmessage.com/330/download_media",
      "workflow": {}
    },
    "played_by": "anonymous"
  }
}

Last updated