ZipMessage API
Search…
⌃K

Webhook Events

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

Conversation created

This event occurs when a new ZipMessage conversation is created. Conversations can be created in any of the following ways:
  • You or a teammate clicks "Create Conversation" in your ZipMessage 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://zipmessage.com/awesomecompany/april-1st-2022-conversation1",
"embed_url": "http://zipmessage.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://zipmessage.com/awesomecompany/april-1st-2022-conversation1#message-330",
"message_embed_url": "http://zipmessage.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": "[email protected]"
},
"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://zipmessage.com/awesomecompany/conversation-with-emma-casel#message-283",
"message_embed_url": "http://zipmessage.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": "[email protected]"
},
"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"
}
}