Skip to content
Amio Docs

Webhooks

Webhooks allow you to receive real-time updates when a specific event occurs, i.e. message is received from a contact. These events are HTTP POST requests being sent to an endpoint of your server. Similarly to Amio Messaging API, body of such request is in JSON format. All events which happen in a specific channel are delivered to a single webhook url (i.e. https://your-server.com/webhook) which you can set in administration.

When you receive a webhook event, you should always return HTTP response in 2xx class, i.e. 200 OK in shortest time possible (we close the connections which takes longer then 60 seconds). If the webhook request fails or exceeds the maximum time, Amio will try to re-deliver the webhook again later (see Webhook Re-Delivery).

📘 Set Webhook URL

  1. Login to app.amio.io.
  2. Pick a channel from channels.
  3. Select tab Webhook and set Webhook Url.

Webhook Content

Section titled “Webhook Content”

All webhooks have following body structure:

{
  "event": "{{EVENT_NAME}}",
  "timestamp" : "{{ISO_8601_TIMESTAMP}}",
  "data" : {
    "{{event type specific data}}"
  }
}
Parameter Type Description
event string Event type name. See Events for complete list of events emitted by Amio.
timestamp string Iso 8601 Timestamp - time when we sent you the webhook.
data object Event type specific data object.

Webhook Re-Delivery

Section titled “Webhook Re-Delivery”

If your webhook fails with response code 4xx or 5xx, Amio will try to re-deliver the webhook again. There are several re-delivery events after 1, 5, 20, 60, 180 and 480 minutes. If all retries fail, the webhook call is discarded.

Events

Section titled “Events”

Different events are fired by Amio. There are common events to all channel types, however, there are also events specific to each channel, see Channel Events chapter for a complete list of channel-specific events.

Message Received

Section titled “Message Received”

This event is fired when a contact sends a message to your channel. Request body contains channel type on which the event was handled as well as id of the contact. Different type of messages can be received based on channel.type.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "{{MESSAGE_ID}}",
    "channel": {
      "id": "{{CHANNEL_ID}}",
      "type": "{{CHANNEL_TYPE}}",
      "name": "{{CHANNEL_NAME}}"
    },
    "contact": {
      "id": "{{CONTACT_ID}}"
    },
    "content": {
      "payload": "What's the weather today?",
      "type": "text"
    },
    "nlp": {
      "intents": [
        {
          "confidence": 0.99847021852548,
          "id": "weather"
        }
      ],
      "native_data": {...}
    },
  }
}
Parameter Type Description
data object Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body except for the nlp key (see below). This key will be present only for received text messages on channels with NLP connected.

Natural Language Processing (NLP)

Section titled “Natural Language Processing (NLP)”

If there’s an NLP connected to your channel, then your Message Received webhook will contain an nlp key with the result provided by the NLP service. Since different NLP services provide different extra capabilities and parameters beyond simple intent/entity extraction, we also include full JSON response from the service.

Parameter Type Description
nlp.intents array of objects List of intents ordered by confidence score.
nlp.intents[].id string Name (or other unique identifier) of the intent.
nlp.intents[].confidence number Confidence score of the intent.
nlp.native_data object Full unmodified JSON response as returned by the NLP service. For more information, please refer to the documentation of the service:
• Wit.ai
• Watson

Messages Delivered

Section titled “Messages Delivered”

This event notifies you of messages that were delivered to your contact.

{
  "event": "messages_delivered",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "messages": [
      { "id": "6456078996108088196" },
      { "id": "6456079002382766981" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}
Parameter Type Description
data.channel object Channel where the data.contact resides in.
data.contact object Contact to whom the messages were delivered.
data.messages array of messages Array of messages that were delivered. Every message will contain message.id. Depending on platform used, the message can contain other fields.
data.delivered_timestamp string Iso 8601 Timestamp. The time of message delivery to the user’s device. This value may vary from webhook timestamp attribute if provided by the platform. If the platform doesn’t provide this time, Amio uses time when the webhook came to our servers.

Message Failed

Section titled “Message Failed”

This event occurs only for some platforms and notifies you about a message that could not be. This may happen when given phone number is wrong or message expires, etc.

{
  "event": "message_failed",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309",
    },
    "message": {
      "id": "6456078996108088196"
    },
    "error": {
      "code": 1,
      "message": "Error while processing the request."
    }
  }
}
Parameter Type Description
data.channel object Channel where the data.contact resides in.
data.contact object Contact to whom the message was sent but not delivered.
data.message object Messages which was sent, will contain only message.id.
data.error.code number Error code, see errors below.
data.error.message string Detail message of an error, see errors below.

Errors

Section titled “Errors”
Error Code Reason
1 Error while processing the request.
2 Sending messages to this user is blocked.
3 Cannot find user for given phone number.
4 Message failed to be delivered within 24 hours.

Messages Read

Section titled “Messages Read”

This event notifies you of messages that a contact has read.

{
  "event": "messages_read",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "last_read_timestamp": "2016-10-06T13:40:13Z"
  }
}
Parameter Type Description
data.channel object Channel where the data.contact resides in.
data.contact object Contact that has read messages delivered.
last_read_timestamp string Iso 8601 Timestamp
All messages before this timestamp were read.

Message Echo

Section titled “Message Echo”

Message echo event is invoked whenever a message is sent to a contact. This callback allows you to track all messages being sent no matter if they’re sent by your channel or by someone else. For example, messages sent to Facebook users directly from Facebook Page administration or messages sent by some other Amio channel can be easily recorded.

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "{{MESSAGE_ID}}",
    "channel": {
      "id": "{{CHANNEL_ID}}",
      "type": "{{CHANNEL_TYPE}}",
      "name": "{{CHANNEL_NAME}}"
    },
    "contact": {
      "id": "{{CONTACT_ID}}"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
Parameter Type Description
data object Object representing message which is echoed. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body.

Channel Events

Section titled “Channel Events”

Security

Section titled “Security”

Once your server is configured to receive webhook events, it’ll listen for any payload sent to the endpoint you configured. For security reasons, you probably want to limit requests to those coming from Amio. There are few ways to go about this, for example, you could opt to whitelist requests from Amio’s IP address but a far easier method is to set up a secret token and validate the information using secret token.

You can find your secret token in Amio settings.

Amio uses this secret token to create a hash signature with each payload. The HTTP request will contain an X-Hub-Signature header which contains the SHA1 signature of the request payload, using the secret token as the key and prefixed with sha1= string. Your callback endpoint can verify this signature to validate the integrity and origin of the payload.

Here is the code how to calculate X-Hub-Signature:

const crypto = require('crypto')


function calculateXHubSignature(secret, body /* as string */) {
  const hmac = crypto.createHmac('sha1', secret)
  hmac.update(body)
  return `sha1=${hmac.digest('hex')}`
}

Java

import org.apache.commons.codec.binary.Hex


import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
import java.nio.charset.Charset


class WebhookSecurityService {


  public static String calculateXHubSignature(String secret, String body) {
    Mac hmac = Mac.getInstance("HmacSHA1");
    hmac.init(new SecretKeySpec(secret.getBytes(Charset.forName("UTF-8")), "HmacSHA1"));
    return "sha1=" + Hex.encodeHexString(hmac.doFinal(body.getBytes(Charset.forName("UTF-8"))));
  }
}
// credits goes to Michal Pustějovský <mpustejovsky@dpd.cz>


using System;
using System.Text;
using System.Security.Cryptography;


namespace Webhook
{
    public class WebhookSecurityService
    {
        public string WebhookSecurity(string secret, string body)
        {
            var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(secret));
            var byteHash = hmac.ComputeHash(Encoding.UTF8.GetBytes(body));
            return "sha1=" + BitConverter.ToString(byteHash).Replace("-", "").ToLower();
        }
    }
}

Verify your algorithm with following values:

secret = 'WebhookSecret'
body = '{"event":"messages_delivered","timestamp":"2018-03-01T11:54:14.886Z","data":{"channel":{"id":"viber_service_messages_test","type":"viber"},"contact":{"phone_number":"+420606123456"},"messages":[{"id":"151990525359991"}]}}'

The calculated X-Hub-Signature should equal to sha1=cb041d03489e961730cb6c7a6d1edf58ae88ef13.

Channel-specific webhook events

Section titled “Channel-specific webhook events”

Select a channel to see its specifics.

Amio Chat: Overview

Section titled “Amio Chat: Overview”

See general webhook documentation for instructions on how to set up webhooks for your app and further details. This section will walk you through all common webhooks as well as webhooks specific to Amio Chat platform.

Amio Chat: Message Received

Section titled “Amio Chat: Message Received”

This event is fired whenever a contact sends a message to your channel.

{
  "event": "message_received",
  "timestamp": "2019-03-27T18:42:48Z",
  "data": {
    "id": "6456078996108099701",
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!",
      "quick_reply": {
        "payload": "DEVELOPER_DEFINED_PAYLOAD"
      }
    },
    "nlp": {...}
  }
}
Parameter Type Description
data object Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

Amio Chat: Messages Delivered

Section titled “Amio Chat: Messages Delivered”

This event occurs when a message has been delivered to contact.

{
  "event": "messages_delivered",
  "timestamp" : "2016-10-06T13:42:48Z",
  "data" : {
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "messages": [
      { "id": "6456078996108099701" },
      { "id": "6456078996108097880" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}
Parameter Type Description
data.channel object Channel where the data.contact resides in.
data.contact object Contact to whom the messages were delivered.
data.messages array Array of messages that were delivered. Every message will contain message.id.
data.delivered_timestamp string Iso 8601 Timestamp. The time of message delivery to the user’s device. This value may vary from webhook timestamp attribute due to delays.

Amio Chat: Messages Read

Section titled “Amio Chat: Messages Read”

This event occurs when a message has been read by the contact.

{
  "event": "messages_read",
  "timestamp" : "2016-10-06T13:42:48Z",
  "data" : {
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "last_read_timestamp": "2016-10-06T13:40:13Z"
  }
}
Parameter Type Description
data.channel object Channel where the data.contact resides in.
data.contact object Contact that has read messages delivered.
last_read_timestamp string Iso 8601 Timestamp
All messages that were delivered before this timestamp were read. (It doesn’t mean “time when the messages were read”.)

Amio Chat: Message Echo

Section titled “Amio Chat: Message Echo”

Message echo event is invoked whenever message is sent to user. This callback allows you to track all messages being sent no matter if they’re sent by you or by someone else.

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108099701",
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
Parameter Type Description
data object Object representing message which is echoed. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body.

Amio Chat: Notification Received

Section titled “Amio Chat: Notification Received”

Notification event is invoked by the client and can be used to send any notification events like chat opened, chat closed, etc.

{
  "event": "notification",
  "timestamp": "2019-03-28T12:36:34.873Z",
  "data": {
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "type": "custom",
    "payload": {
      "any": "arbitrary data"
    }
  }
}
Parameter Type Description
data object Object representing notification received. Only custom notification is supported from client side, see Send Notification for more details.

Amio Chat: Postback Received

Section titled “Amio Chat: Postback Received”

This event occurs when the user presses a Postback Button (which can be a part of a Structured Message). You can react to this event by performing an action or by sending a reply.

{
  "event": "postback",
  "timestamp": "2020-03-01T15:49:02.243Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "postback": {
      "payload": "{{DEVELOPER_DEFINED_PAYLOAD}}"
    }
  }
}
Parameter Type Description
postback.payload string Payload of the Postback Button that has been pressed.