Introduction
Authentication
Authenticate your requests using access token available in Amio settings. Your access token carry many privileges, so keep it secret! You can authenticate your requests using Authorization HTTP header or by sending access token in query parameters.
curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer {{OAUTH_TOKEN}}" https://api.amio.io/v1/messagescurl -X POST -H "Content-Type: application/json" https://amio.io/api/v1/messages?access_token={{OAUTH_TOKEN}}Get Access Token
- Login to app.amio.io.
- Navigate to API settings.
- Copy the access token.
Requests
All API requests must be made over HTTPS with base URL https://api.amio.io/v1/. Data is sent and received in JSON format. Where possible, Amio API leverages appropriate HTTP verbs for requests.
GET
Used for resource retrieval.
POST
Resource creation or any other non-idempotent operation.
PUT
Used for idempotent operation as collection replacement etc.
PATCH
Update resource. Use {"key": "value"} for property update or create and {"key": null} for delete.
DELETE
Deletes a resource.
Responses
HTTP status codes are used to communicate result of your request.
200 OK
The request was successful.
201 Created
The request was successful and resource was created.
204 No Content
The request was successful and resource was deleted.
400 Bad Request
When the request could not be understood.
401 Unauthorized
Unauthorized request, i.e. missing access token.
403 Forbidden
The request is forbidden due to security reasons.
404 Not Found
Requested resource cannot be found.
405 Method Not Allowed
Requested method was not allowed, some other HTTP method is required.
422 Unprocessable Entity
The request was understood but cannot be processed as some validation error might occur. This might also represent an invalid state of the application or other similar problems.
429 Too Many Requests
In case you exceed maximum number of requests within given period, you receive this error response for any consequent requests. See Rate Limiting for more details.
502 Bad Gateway
In case an underlying API responds with an error. For example this might occur when message is being send to Facebook Messenger and Facebook page is disconnected from Amio.
All responses with status code 201 Created contain Location header with actual location of newly created resource, i.e. Location: https://api.amio.io/v1/channels/{channel_id}.
Errors
As the HTTP status code returns a basic information about an error, we provide additional data in response body for further error indication. All errors have following format:
{
"timestamp": "{{iso_8601_timestamp}}",
"status": {
"code": "{{HTTP_STATUS_CODE}}",
"message": "{{HTTP_STATUS_MESSAGE}}"
},
"errors": ["{{LIST_OF_DETAIL_ERRORS}}"]
}{
"timestamp": "2016-12-21T11:17:56.397Z",
"status": {
"code": "405",
"message": "Method Not Allowed"
},
"errors": [
{
"message": "Method POST is not allowed for resource /users."
}
]
}{
"timestamp": "2016-12-21T11:17:56.397Z",
"status": {
"code": "422",
"message": "Unprocessable Entity"
},
"errors": [
{
"field": "recipient",
"rejected_value": null,
"message": "Property 'recipient' cannot be null."
}
]
}Pagination
A resource which returns a list doesn't return all results at once. Instead, the number of results is constrained and you can traverse the results. For that purpose, the list requests accept the parameters max and offset.
max
10
Maximal number of returned resources. Maximal allowed value is 100.
offset
0
The offset from the first result to list from.
All list responses return a number of total results in HTTP response header.
x-total-count
Number of total results.
An example which returns the 21st to 30th resource:
curl-H "Content-Type: application/json" -H "Authorization: Bearer {{OAUTH_TOKEN}}" https://api.amio.io/v1/channels?max=10&offset=20Rate Limiting
Amio API has different rate limits for each pricing plan. We limit number of requests you can do within a hour. And number of simultaneous connections you can have opened to Amio servers.
Free
1000
3
Developer
2000
10
Enterprise
custom
custom
You can check the returned HTTP headers of any API request to see your current rate limit status for maximum number of requests:
curl -i https://api.amio.io/v1/channels/{{channel_id}}
HTTP/1.1 200 OK
Date: Mon, 01 Jul 2013 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1491820066X-RateLimit-Limit
The maximum number of requests that you are permitted to make per hour.
X-RateLimit-Remaining
Remaining number of requests.
X-RateLimit-Reset
Remaining time before the rate limit resets, in UTC epoch seconds.
Once you go over the rate limit you will receive an error response:
{
"timestamp": "2016-12-21T11:17:56.397Z",
"status": {
"code": "429",
"message": "Too Many Requests"
},
"errors": [
{
"message": "You have exceeded maximum number of requests and have been temporarily blocked. See documentation for more details: https://docs.amio.io/reference#rate-limiting"
}
]
}Locale
Messages
Messages resource is the main entry point for sending messages. You have to specify a channel and contact to deliver the message.
The structure of JSON body is the same for all the channels. However, not all message types are supported by all channels.
Following chapters highlight only API requests that are common for all platforms. See platform specific documentation for more details:
List Messages
id
string
Id of the message.
direction
string
Specifies if the message has been received or sent: received, sent.
delivered
string
Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.
read
string
Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.
channel
object
Channel in which the message was sent or received.
contact
object
Message belongs to a contact.
content
object
Content of the message.
Send Message
Metadata
Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"any": "arbitrary data"
}
}Notifications
Notifications resource is used for sending various events like messages read or typing to the contact. If you're looking for events received from the contact, see the Webhooks documentation.
Notifications are available only on some platforms. See platform specific documentation for more details:
Channels
Channel represents a medium through which you can send and receive messages. There are different channel types (facebook_messenger, viber, etc.).
See platform specific documentation for more details:
List Channels
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger, viber, mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Get Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger, viber, mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Create Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger, viber, mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Update Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger, viber, mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Remove webhook
Set webhook attribute to null if you'd like to remove channel webhook.
Contacts
Contact represents the end user on given channel. Contact is automatically created whenever you receive a message from the user for the first time. However, there are also different ways how you can create the contact (i.e. for Mobile platform the user is created when you send a message to the given phone number).
Contact Merging
Amio doesn't implement any type of contact merging for one user on different platforms.
See channel specific requests to see differences between contacts on each channel:
List Contacts
Get Contact
Delete Contact
Deleting a contact will also delete its conversation, messages and linked files.
Settings
Settings resource is used for setting up certain properties of a channel like get started button, menu, etc.
Settings are available only on some channels:
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).
All webhooks have following body structure:
{
"event": "{{EVENT_NAME}}",
"timestamp" : "{{ISO_8601_TIMESTAMP}}",
"data" : {
"{{event type specific data}}"
}
}data
object
Event type specific data object.
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.
Set Webhook URL
- Login to app.amio.io.
- Pick a channel from channels.
- Select tab Webhook and set Webhook Url.
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
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": {}
},
}
}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 integration connected.
If there's an NLP integration 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.
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.
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"
}
}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
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."
}
}
}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.
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
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"
}
}data.channel
object
Channel where the data.contact resides in.
data.contact
object
Contact that has read messages delivered.
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"
}
}
}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
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')}`
}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.
Amio Chat (Beta)
Amio Chat is in Beta!
Amio Chat brings you the ability to easily create your own web chat. This API documentation describes how to manage Amio Chat channels and send messages to users. To implement your custom web chat, use Amio Chat SDK for Web.
Messages
Message resource is the main entry point for sending messages. To send a message, you have to specify an Amio Chat contact id. You receive contact.id when the user starts a conversation with you, see Message Received webhook.
List Messages
id
string
Id of the message.
direction
string
Specifies if the message has been received or sent: received, sent.
delivered
string
Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.
read
string
Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.
channel
object
Channel in which the message was sent or received.
contact
object
Message belongs to a contact.
content
object
Content of the message.
Metadata
Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"any": "arbitrary data"
}
}Notifications
Notifications resource is used for sending various events like messages read or typing to the contact. If you're looking for events received from the contact, see the Webhooks documentation.
List Channels
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: amio_chat.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Get Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: amio_chat.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Create Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: amio_chat.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Update Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: amio_chat.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
Remove webhook
Set webhook attribute to null if you'd like to remove channel webhook.
Contacts
Contact represents the Amio chat user. Contact is automatically created whenever you receive a message from the user for the first time.
List Contacts
Get Contact
Settings
Amio Chat allows you to restrict domains where the chat will be running, using a domain whitelist.
Get Settings
domains_whitelist
array
List of domains allowed for cross origin requests (CORS) during connection to Amio Chat servers.
Update Settings
Delete Settings
You can delete any settings with PATCH request setting the parameter to null, i.e. {"domains_whitelist": null}.
domains_whitelist
array
List of domains allowed for cross origin requests (CORS) during connection to Amio Chat servers. If this value is set to null or an empty list, then all connection attempts will be refused.
Domains Whitelist
Amio Chat allows to restrict domains where the web chat will be running. Only the whitelisted domains will be allowed for cross origin requests (CORS) during connection to Amio Chat servers.
When adding domains to the whitelist, please keep in mind that the whole fully qualified domain name, including protocol, is required. If your server uses non-standard port, then you have to include it, too (standard ports are 80 for HTTP, 443 for HTTPS). localhost is allowed and has to be whitelisted if you want to run your code locally.
If the domain whitelist is set to null or an empty list [ ], then no connection will be allowed.
Default domain whitelist value is null which means that no connection will be allowed.
Webhooks
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.
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!"
},
"nlp": {}
}
}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.
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"
}
}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.
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"
}
}data.channel
object
Channel where the data.contact resides in.
data.contact
object
Contact that has read messages delivered.
last_read_timestamp
string
All messages that were delivered before this timestamp were read. (It doesn't mean "time when the messages were read".)
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"
}
}
}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.
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"
}
}
}data
object
Object representing notification received. Only custom notification is supported from client side, see Send Notification for more details.
Facebook Messenger
See Amio Documentation for getting started manuals and complete description of Facebook Messenger platform.
Messages
Message resource is the main entry point for sending messages. To send a message, you have to specify a Facebook contact with one of the following attributes:
- Contact Id - For example
contact.id, you've received with first message received from the user, see Message Received webhook. - Phone Number - A phone number you already have.
- User Ref - Reference you received from Opt-in Webhook.
Contact Id
You receive contact.id when the user starts a conversation with you, see Entry Points for more details.
{
"contact": {
"id": "6456078781510718339"
},
"channel": {},
"content": {}
}{
"id": "...",
"contact": {
"id": "6456078781510718339"
},
"channel": {},
"content": {}
}Phone Number
You can send a message using a phone number you already have (see Phone Number Entry Point for more details). Attributes first_name and last_name are optional and just help to match the phone number with an existing Facebook User.
{
"contact": {
"phone_number": "+1 (555) 857-6309",
"first_name": "Anthony",
"last_name": "Hopkins"
},
"channel": {},
"content": {}
}{
"id": "...",
"contact": {
"id": "15234390803083474",
"phone_number": "15558576309"
},
"channel": {},
"content": {}
}Opt-in and Messages Delivered Webhooks
When you send a message using phone number, you can listen to Opt-in Webhook which is fired when the user confirms your request. You should however also listen to Messages Delivered Webhook which is fired for any further message sent after the user opts in.
Phone Number Format
Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.
Message Tags
Facebook requires you to comply with subscription messages policy when sending messages using phone number. This applies for all messages sent before the user opts in to receive messages from you.
Therefore, when you send messages before the opt-in, Amio automatically sets tag non_promotional_subscription (see tags) to your messages. You can set appropriate message tag which will be used after the user opts in (i.e. shipping_update).
User Ref
Opt-in Webhook delivers a user_ref attribute which can be used for sending the first message to the user.
List Messages
id
string
Id of the message.
direction
string
Specifies if the message has been received or sent: received, sent.
delivered
string
Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.
read
string
Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.
channel
object
Channel in which the message was sent or received.
contact
object
Message belongs to a contact.
content
object
Content of the message
Location
Location Messages are only Received
On Facebook Messenger, location messages cannot be sent however they can be received from the user, see Receive Message webhooks.
{
"channel": { },
"contact": { },
"content": {
"type": "location",
"payload": {
"latitude": 50.0902163,
"longitude": 14.3973905
}
}
}content.type
string
Message type location.
content.payload.latitude
double
Location sent by user - latitude.
content.payload.longitude
double
Location sent by user -
longitude.
Receipt
Receipt type of message is suitable for sending order confirmation with all items listed, address and payment summary.
Facebook Messenger receipt.
Receipt detail is shown when user taps on the receipt.
Structure
Structure messages allows you to send well formatted message containing image, title, description, link and action buttons. This format is suitable when you'd like to send messages with visual content and possible call to action buttons, i.e. today's menu of your restaurant.
Different Structure Messages
Structure message can be composed from subset of attributes: title can be combined with one or more attributes (i.e. Title & Text, Title, Text & Image, etc.), text can be combined only with title or button (Title & Text and Text & Button).
Structure - Horizontal Scroll
It is also possible to send multiple structured messages. They are displayed as a horizontal scroll within the Facebook Messenger.
Buttons
Buttons can be used in Structure messages. They provide the user with ability to perform a predefined action, such as opening Messenger webview, send a postback message, share a content, and more.
- Url Button
- Postback Button
- Call Button
- Share Button (coming soon)
- Buy Button (coming soon)
- Log In Button (coming soon)
- Log Out Button (coming soon)
The Url Button opens an in-app Messenger webview (browser) with given address.
buttons: [
{
"type": "url",
"title": "Freedom",
"payload": "https://en.wikipedia.org/wiki/Liberty"
}
]
type*
string
Must be set to url.
title*
string
Title of the button. Max size is 20 characters.
payload*
string
Url to be opened.
Requires Domain Whitelisting
Url passed to the webview with url button must be whitelisted (including subdomains). See domain whitelisting.
Postback Button
When the user taps on the postback button, it sends developer-defined payload back on Postback Received webhook. You can perform an action or reply back when this happens.
buttons: [
{
"type": "postback",
"title": "List Items",
"payload": "{{PASS_THROUGH_PARAM}}"
}
]
type*
string
Must be set to postback.
title*
string
Title of the button. Max size is 20 characters.
payload*
string
Any arbitrary data you can send to Postback Received webhook. Max size is 1000 characters.
Call Button initiates a phone call.
buttons: [
{
"type": "phone",
"title": "Call Us",
"payload": "+1 (555) 857-6309"
}
]
type*
string
Must be set to phone.
title*
string
Title of the button. Max size is 20 characters.
payload*
string
Phone number that will be dialed. Make sure the phone number is in international format.
Quick Replies
Quick Replies are buttons with a set of pre-defined short replies that appear above the user input, making the keyboard less important. When a button is tapped, the message is sent as a text and you'll receive it to your webhook. The buttons are dismissed as soon as user taps one or reply with own text.
Quick Replies can be attached to any Message type in the content.quick_replies attribute.
{
"channel": { },
"contact": { },
"content": {
"type": "...",
"payload": "...",
"quick_replies": [
{ "..." },
{ "..." },
{ "..." }
]
}
}quick_replies
array of objects
Holds a list of maximally 11 objects of Text Quick Reply, User Location Quick Reply, Email Quick Reply or Phone Number Quick Reply type.
Text Quick Replies show buttons with text and optionally a small image icon. Each button can also hold a developer-defined payload, which is invisible to the user but can be used for automated processing. When the user taps on the button, it fires Message Received webhook with text and developer payload if specified.
"quick_replies": [
{
"type": "text",
"title": "Pilsner Urquell",
"payload": "DEVELOPER_DEFINED_PAYLOAD",
"image_url": "http://www.logotypes101.com/logos/778/70D1EF7E13BFAC232F2D05DE2E5594E0/pubisc.png"
},
{
"type": "text",
"title": "Heineken",
"payload": "DEVELOPER_DEFINED_PAYLOAD",
"image_url": "http://www.logotypes101.com/free_vector_logo_png/33082/85D3F063102F2476DC36D26D4D7A15C1/Heineken29"
}
]
type*
string
Must be set to text.
title*
string
Button title with limit of 20 character; longer text gets truncated.
payload*
string
Developer-defined payload with limit of 1000 character. This payload is delivered back together with title as a text message in Message Received webhook.
image_url
string
Image to be displayed on the button. It should have dimension of at least 24x24 px.
UX - `payload` might not be delivered
Be aware that the user might send the reply by typing it into user input. In this case you don't receive the payload metadata. However, you should handle this message same as the user taps on the quick reply button.
Users can be prompt for their location via quick replies. It shows a Send Location button. When the user taps on the button, it fires Message Received webhook with location coordinates.
"quick_replies": [
{
"type": "location"
}
]
type*
string
Must be set to location.
Email can also be requested using a quick reply. If the user has an email set in the profile, then it will be pre-filed as a quick reply button. When the user taps on the button, it fires Message Received webhook with text containing his email address.
"quick_replies": [
{
"type": "email"
}
]
type*
string
Must be set to email.
Phone number quick reply allows you to easily ask for users' phone number. If the user has a phone number set in the profile, then it will be pre-filed as a quick reply button. When the user taps on the button, it fires Message Received webhook with text containing his phone number.
"quick_replies": [
{
"type": "phone_number"
}
]
type*
string
Must be set to phone_number.
Metadata
Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"any": "arbitrary data"
}
}Reserved metadata keywords
platform_metadata - Metadata to be sent directly to Facebook Messenger API, see Platform Metadata below.
tag - Facebook Messenger allows to send messages with tags, see Message Tags documentation.
Facebook Messenger API has its own concept of metadata. You can send metadata as a string with any message, see Facebook Messenger API documentation. Amio API reserves platform_metadata keyword to be mapped to original Facebook Messenger metadata attribute.
You can use platform_metadata attribute to send metadata directly to Facebook Messenger API. This can be received by other programs listening on the same Messenger account but not using Amio API.
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"platform_metadata": "these data are going to be sent directly to Facebook Messenger API as metadata attribute"
}
}platform_metadata
string
Platform specific metadata to be sent directly to Facebook Messenger API as a metadata attribute, see Facebook Messenger API documentation. Max size 1000 characters.
Types
Facebook Messenger types are used to explicitly specify the purpose of a message and ensure that given message complies with Facebook policies. Amio handles message types automatically so you don't have to care about setting this attribute. However, you can specify a message type for custom scenarios.
To send a message type, you can use type reserved keyword in metadata attribute:
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"type": "response"
}
}type
string
Message type: response, update. Type can be set only if Tags are not used.response (default): Message is in response to a received message. This includes promotional and non-promotional messages sent inside the 24-hour standard messaging window or under the 24+1 policy. For example, use this tag to respond if a person asks for a reservation confirmation or an status update.update: Message is being sent proactively and is not in response to a received message. This includes promotional and non-promotional messages sent inside the the 24-hour standard messaging window or under the 24+1 policy.
Notifications
Notifications resource is used for sending various events like messages read or typing to the contact. If you're looking for events received from the contact, see the Webhooks documentation.
List Channels
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
facebook_page
object
Represents a facebook page connected to the channel. You can send and receive message only If facebook page is connected.
facebook_page.id
string
Id of the connected page.
facebook_page.name
string
Name of the facebook page.
facebook_page.category
string
Category of the facebook page.
facebook_page.access_token
string
Long lived facebook page access token with required permission.
Get Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
facebook_page
object
Represents a facebook page connected to the channel. You can send and receive message only If facebook page is connected.
facebook_page.id
string
Id of the connected page.
facebook_page.name
string
Name of the facebook page.
facebook_page.category
string
Category of the facebook page.
facebook_page.access_token
string
Long lived facebook page access token with required permission.
Create Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
facebook_page
object
Id of the connected page.
facebook_page.name
string
Name of the facebook page.
facebook_page.category
string
Category of the facebook page.
facebook_page.access_token
string
Long or short lived facebook page access token with required permission.
Update Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: facebook_messenger.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
facebook_page
object
Id of the connected page.
facebook_page.name
string
Name of the facebook page.
facebook_page.category
string
Category of the facebook page.
facebook_page.access_token
string
Long lived facebook page access token with required permission.
Remove webhook
Set webhook attribute to null if you'd like to remove channel webhook.
Contacts
Contact represents the Facebook Messenger user. Contact is automatically created whenever you receive a message from the user for the first time. However, there are also different ways how the contact is created (i.e. when you send a message to the Facebook Messenger user using phone number you already have, see Facebook Messenger Entry Points).
List Contacts
id
string
Id of the contact. Id is unique across channels and is generated by Amio.
name
string
Name of the contact.
gender
string
User's gender either male or female.
time_zone
string
Time zone set by the user.
photo_url
string
Url to profile picture of the user.
Get Contact
id
string
Id of the contact. Id is unique across channels and is generated by Amio.
phone_number
string
Phone number of the contact (E.164 format). Only available if you have previously sent a message to this contact using a phone number. For more details see Using phone number.
user_ref
string
User_ref instead of id until you get a real id. For more details have a look at how Checkbox plugin works
name
string
Name of the contact.
gender
string
User's gender either male or female.
time_zone
string
Time zone set by the user.
photo_url
string
Url to profile picture of the user.
Settings
Facebook Messenger allows you to set a variety of items which enhance the feel and look of your Messenger channel for your users:
Facebook API Rate Limits
All settings requests directly interact with Facebook API. Unlike other Facebook API endpoints, this endpoint has low rate limits. Amio API will inform you when Facebook API rate limits are reached. It usually takes several minutes until Facebook resets the rate limits.
Get Settings
get_started_button
object
Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.
get_started_button.payload
string
Any arbitrary data you will receive in Postback Received webhook when a user clicks the button.
menu
array
List of the menu for different locales. Given the menu is displayed based on the user's locale preference. If you want to set the menu, get started button is required as well. When setting a menu, at least one default locale menu is required. See Menu chapter for more details.
menu.[ ].locale
string
Specifies locale of given menu. Value has to be in form of locale or default.
menu.[ ].items
object
List of menu item objects. Maximum allowed size is 3.
user_inputs
array
List of settings for user inputs for different locales. If you want to disable user inputs then the menu is required to be set. When setting user input, at least one default locale user input is required. See User Inputs chapter for more details.
user_inputs.[ ].locale
string
Specifies locale of given user input. Value has to be in form of locale or default.
user_inputs.[ ].enabled
boolean
Set to false in order to disable users' input, set to true otherwise.
domains_whitelist
array
Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.
Update Settings
Delete Settings
You can delete any settings with PATCH request setting the parameter to null, i.e. {"menu": null}.
get_started_button
object
Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.
get_started_button.payload
string
Any arbitrary data you will receive in Postback Received webhook when a user clicks the button.
menu
array
List of the menu for different locales. Given the menu is displayed based on the user's locale preference. If you want to set the menu, get started button is required as well. When setting a menu, at least one default locale menu is required. See Menu chapter for more details.
menu[].items
array[object]
List of menu item objects. Maximum allowed size is 3.
user_inputs
array[object]
List of settings for user inputs for different locales. If you want to disable user inputs then the menu is required to be set. When setting user input, at least one default locale user input is required. See User Inputs chapter for more details.
user_inputs[].locale
string
Specifies locale of given user input. Value has to be in form of locale or default.
user_inputs[].enabled
boolean
Set to false in order to disable users' input, set to true otherwise.
domains_whitelist
array[string]
Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.
Get Started Button
Get Started Button is visible on the welcome screen when the user comes for the first time. If the user tapes the button, it will trigger Postback Received webhook and deliver the user's page-scoped id.
You can then present a personalised message to greet the user or provide a structured message with buttons to prompt him or her to take an action. The button is a good mean to increase conversions. Adding a "Get Started" button resolves the issue of users not knowing what to write to break the ice with your bot.
{
"get_started_button": {
"payload": "{{GET_STARTED_PAYLOAD}}"
}
}get_started_button
object
Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.
get_started_button.payload
string
Any arbitrary data you will receive in Postback Received webhook when a user clicks the button.
Get started button on conversation start.
Menu
Creating a menu in Facebook Messenger, you can highlight important actions or provide a link to a webpage. Menu for Facebook Messenger is hierarchical and consists of different menu items:
The Menu requires Get Started Button
You must set a Get Started Button if you want to use the menu in Facebook Messenger.
Testing Tips
Facebook Messenger menu is cached by default (it is updated after a certain period of time). If you update the menu while testing, you can force this update to happen by deleting the messenger thread and then beginning the conversation once again.
The Menu is visible only if:
- Facebook Messenger has a version 106 and above.
- The attached Facebook page must be published.
{
"menu": [
{
"locale": "default",
"items": [
{
"type": "url",
"title": "URL Item",
"payload": "http://www.google.com/"
},
{
"type": "postback",
"title": "POSTBACK Item",
"payload": "POSTBACK DATA"
},
{
"type": "menu",
"title": "NESTED Item",
"payload": {
"items": [
{
"type": "url",
"title": "NESTED URL Item",
"payload": "http://www.google.com/"
}
]
}
}
]
}
]
}menu[].items
array[object]
List of menu item objects. Maximum allowed size is 3.
type
string
Must be set to url.
title
string
Title of the menu item. A maximum size of 30 characters.
payload
string
Must be a valid URL.
type
string
Must be set to postback.
title
string
Title of the menu item. A maximum size of 30 characters.
payload
string
This data will be sent back to Postback Received webhook. A maximum size of 1000 characters.
type
string
Must be set to menu. The maximal hierarchical depth is 3 levels.
title
string
Title of the menu item. A maximum size of 30 characters.
payload
object
Object with attribute items holding an array of nested menu items.
The maximum number of items is 5 objects.
Menu can have a deep nesting up to level of 3.
Menu in Facebook Messenger.
Nested menu items.
User Inputs
You can disable the user from writing you a message back using user_inputs settings. This forces the user to use only buttons provided in structured messages or in the menu.
{
"user_inputs": [
{
"locale": "default",
"enabled": true
}
]
}user_inputs[].locale
string
Specifies locale of given menu. Value has to be in form of locale or default.
user_inputs[].enabled
boolean
Set to false in order to disable users' input, set to true otherwise.
User Inputs requires Menu
You must set a Menu if you want to disable user input.
Disabled user input.
Domains Whitelist
Some features like Checkbox Plugin require domains to be whitelisted.
{
"domains_whitelist": [
"https://app.amio.io"
]
}domains_whitelist
array[string]
Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.
Whitelisting in Facebook Page Settings
In addition to domains whitelist API, you can whitelist domains in Facebook Page administration:
- Click Settings in your Facebook Page.
- Click Messenger Platform on the left menu.
- Edit domains in Whitelisted Domains sectionn.
Webhooks
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 Facebook Messenger platform.
Message Received
This event is fired whenever a contact sends a message to your Facebook page.
Amio Persists Message Files
All incoming messages having a file url attachments (i.e. Image Message, Video Message, etc.) are persisted on Amio servers due to expiration reasons.
{
"event": "message_received",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"id": "6456078996108088196",
"channel": {
"id": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339"
},
"content": {
"type": "text",
"payload": "That's really nice that I can write you here. You guys rock!",
"quick_reply": {
"payload": "DEVELOPER_DEFINED_PAYLOAD"
}
},
"nlp": {}
}
}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.
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": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339"
},
"messages": [
{ "id": "6456078996108088196" },
{ "id": "6456079002382766981" }
],
"delivered_timestamp": "2016-10-06T13:40:01Z"
}
}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.
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": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339"
},
"last_read_timestamp": "2016-10-06T13:40:13Z"
}
}data.channel
object
Channel where the data.contact resides in.
data.contact
object
Contact that has read messages delivered.
last_read_timestamp
string
All messages that were sent before this timestamp were read. (It doesn't mean "time when the messages were read".)
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. For example messages sent to Facebook users directly from Facebook Page administration can be easily recorded. The same situation can happen when you reply the user from Amio integration (i.e. you reply from Zendesk).
{
"event": "message_echo",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"id": "6456078996108088196",
"channel": {
"id": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339"
},
"content": {
"type": "text",
"payload": "We know, we try really hard to bring always something more to our beloved customers!"
},
"metadata": {
"any": "arbitrary data"
}
}
}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.
Postback Received
This callback occurs when the user presses Postback Button or Get Started Button. You can use this event to perform certain action or to reply back.
{
"event": "postback",
"timestamp": "2017-03-01T15:49:02.243Z",
"data": {
"channel": {
"id": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339"
},
"postback": {
"payload": "{{PASS_THROUGH_PARAM}}"
}
}
}Opt-in
Opt-in webhook is fired for several actions and is generally meant for binding a user in your application. This webhook is fired when:
- Send to Messenger is clicked.
- Checkbox Plugin is ticked.
- Phone Number Matching procedure is called.
Opt-in for Send to Messenger
When user presses Send to Messenger button, you will receive following webhook.
{
"event": "opt_in",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"channel": {
"id": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339"
},
"opt_in": {
"type": "send_to_messenger",
"payload": "{{PASS_THROUGH_PARAM}}"
}
}
}opt_in.type
string
Describes what type of opt-in this is. In case of Send to Messenger, this will always be send_to_messenger.
opt_in.payload
string
Data set in Send to Messenger Button as data-ref attribute.
Opt-in for Checkbox
When user ticks Checkbox plugin, you will receive following webhook.
{
"event": "opt_in",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"channel": {
"id": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339",
"user_ref": "{{YOUR_CUSTOM_USER_REF}}" // set on frontend checkbox plugin
},
"opt_in": {
"type": "checkbox",
"payload": "{{PASS_THROUGH_PARAM}}"
}
}
}contact.user_ref
string
Data that has been set in checkbox plugin user_ref attribute. It is should be uniquely generated string ID (unique for each render).
opt_in.type
string
Describes what type of opt-in this is. In case of Checkbox plugin, this will always be checkbox.
opt_in.payload
string
Data that has been set in checkbox plugin ref attribute.
Opt-in for Phone Number Matching
This webhook is sent when a user accepts the message request sent to his phone number using Phone Number Entry Point.
{
"event": "opt_in",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"channel": {
"id": "6456078759331238786",
"type": "facebook_messenger"
},
"contact": {
"id": "6456078781510718339",
"phone_number": "15558576309"
},
"opt_in": {
"type": "phone_number"
}
}
}opt_in.type
string
Describes what type of opt-in this is. In case of Phone Number Matching, this will always be phone_number.
Mobile
Mobile channel is primarily used for SMS send and receive. Amio integrates with 3rd party providers which you can connect in administration and use Amio API to send messages.
Messages
Message resource is the main entry point for sending messages. To send a message, you have to specify a Mobile contact with a phone number you already have.
{
"contact": {
"id": "+1 (555) 857-6309"
},
"channel": {},
"content": {}
}{
"id": "...",
"contact": {
"id": "6456078781510718339",
"phone_number": "15558576309"
},
"channel": {},
"content": {}
}Phone Number Format
Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.
Metadata
Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"any": "arbitrary data"
}
}List Channels
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
provider
object
Represents a provider used to receive and deliver messages.
provider.type
string
Name of the service provider: messagebird.
provider.sender_id
string
Phone number registered at the provider to be used as a sender number. Any string in case of using shared number.
provider.access_token
string
Access token used for authorising requests to provider.
provider.signing_key
string
Signature key used for verifying that incoming webhook came from MessageBird.
provider.status_webhook_url
string
Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.
provider.receive_webhook_url
string
Amio webhook url to be used by provider to deliver incoming SMS messages.
Get Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
provider
object
Represents a provider used to receive and deliver messages.
provider.type
string
Name of the service provider: messagebird.
provider.sender_id
string
Phone number registered at the provider to be used as a sender number. Any string in case of using shared number.
provider.access_token
string
Access token used for authorising requests to provider.
provider.signing_key
string
Signature key used for verifying that incoming webhook came from MessageBird.
provider.status_webhook_url
string
Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.
provider.receive_webhook_url
string
Amio webhook url to be used by provider to deliver incoming SMS messages.
Create Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
provider
object
Represents a provider used to receive and deliver messages.
provider.type
string
Name of the service provider: messagebird.
provider.sender_id
string
Phone number registered at the provider or custom sender ID to be used as a message originator.
provider.access_token
string
Access token used for authorising requests to provider.
provider.signing_key
string
Signature key used for verifying that incoming webhook came from MessageBird.
provider.status_webhook_url
string
Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.
provider.receive_webhook_url
string
Amio webhook url to be used by provider to deliver incoming SMS messages.
Update Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: mobile.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
provider
object
Represents a provider used to receive and deliver messages.
provider.type
string
Name of the service provider: messagebird.
provider.sender_id
string
Phone number registered at the provider or custom sender ID to be used as a message originator.
provider.access_token
string
Access token used for authorising requests to provider.
provider.signing_key
string
Signature key used for verifying that incoming webhook came from MessageBird.
provider.status_webhook_url
string
Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.
provider.receive_webhook_url
string
Amio webhook url to be used by provider to deliver incoming SMS messages.
Remove webhook
Set webhook attribute to null if you'd like to remove channel webhook.
Contacts
Contact represents the mobile number owner. Contact is automatically created whenever you send a message to new phone number or when you receive a message from the user.
List Contacts
id
string
Id of the contact. Id is unique across channels and is generated by Amio.
name
string
Name of the contact. Phone number by default.
Get Contact
id
string
Id of the contact. Id is unique across channels and is generated by Amio.
name
string
Name of the contact. Phone number by default.
Webhooks
See general webhook documentation for instructions on how to set up webhooks for your app and further details.
Message Received
This event is fired whenever a contact sends a message to your dedicated phone number or replies to you in case of shared number.
{
"event": "message_received",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"id": "6456078996108088196",
"channel": {
"id": "6456078759331238786",
"type": "mobile"
},
"contact": {
"id": "6456078781510718339",
"phone_number": "15558576309"
},
"content": {
"type": "text",
"payload": "That's really nice that I can write you back. You guys rock!"
},
"nlp": {}
}
}data
object
Object representing message received. The structure matches Send Message response structure except for the nlp key which is valid only for received messages.
Messages Delivered
This event notifies you of messages that were delivered to your contact.
{
"event": "messages_delivered",
"timestamp" : "2017-12-29T17:26:17.331Z",
"data" : {
"channel": {
"id": "6456078759331238786",
"type": "mobile"
},
"contact": {
"id": "6456078781510718339",
"phone_number": "15558576309"
},
"messages": [
{ "id": "6456078996108088196" }
],
"delivered_timestamp": "2017-12-29T17:26:16.001Z"
}
}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 when Amio servers received notification about message delivery. This value may vary from webhook timestamp attribute due to delays.
Message Failed
This event notifies you of a message that could not be sent. This may happen when given phone number is wrong or when message send expires.
{
"event": "message_failed",
"timestamp" : "2017-12-29T17:26:17.331Z",
"data" : {
"channel": {
"id": "1527759271281586456078759331238786",
"type": "mobile"
},
"contact": {
"id": "6456078781510718339",
"phone_number": "15558576309"
},
"message": {
"id": "6456078996108088196"
},
"error": {
"code": 1,
"message": "Error while processing the request."
}
}
}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.
1
Error while processing the request.
4
Message failed to be delivered within 24 hours.
Message Echo
This event notifies you of a message that could not be sent. This may happen when given phone number is wrong or when message send expires.
{
"event": "message_echo",
"timestamp" : "2017-12-29T17:26:17.331Z",
"data" : {
"id": "6456078996108088196",
"channel": {
"id": "6456078759331238786",
"type": "mobile"
},
"contact": {
"id": "6456078781510718339",
"phone_number": "15558576309"
},
"content": {
"type": "text",
"payload": "We know, we try really hard to bring always something more to our great users!"
},
"metadata": {
"any": "arbitrary data"
}
}
}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.
Messages
Message resource is the main entry point for sending messages. To send a message, you have to specify an Viber contact id. You receive contact.id when the user starts a conversation with you, see Entry Points for more details.
List Messages
id
string
Id of the message.
direction
string
Specifies if the message has been received or sent: received, sent.
delivered
string
Iso 8601 Timestamp - time when the message was delivered. null means that it hasn't been delivered yet.
read
string
Iso 8601 Timestamp - time when the message was read. null means that it hasn't been read yet.
channel
object
Channel in which the message was sent or received.
contact
object
Message belongs to a contact.
content
object
Content of the message
Structure
Structure messages allows you to send well formatted message containing image, title, description, link and action buttons. This format is suitable when you'd like to send messages with visual content and possible call to action buttons, i.e. today's menu of your restaurant.
Structure - Horizontal Scroll
It is also possible to send multiple structured messages. They are displayed as a horizontal scroll within the Viber app.
Buttons
Buttons can be used in Structure messages. They provide the user with ability to perform a predefined action, such as opening a webpage or send a postback message.
- Url Button
- Postback Button
The Url Button opens a browser with given address.
buttons: [
{
"type": "url",
"title": "Freedom",
"payload": "https://en.wikipedia.org/wiki/Liberty"
}
]
type*
string
Must be set to url.
title*
string
Title of the button. It is displayed on one line and the text is truncated with ellipsis (three dots in the end) if exceeds the line. You can fit usually up to 18 characters.
payload*
string
Url to be opened.
When the user taps on the postback button, it sends developer-defined payload back on Postback Received webhook. Tapping on this button also displays the title in the Viber app. You can perform an action or reply back when this happens.
buttons: [
{
"type": "postback",
"title": "List Items",
"payload": "{{PASS_THROUGH_PARAM}}"
}
]
type*
string
Must be set to postback.
title*
string
Title of the button. It is displayed on one line and the text is truncated with ellipsis (three dots in the end) if exceeds the line. You can fit usually up to 18 characters.
payload*
string
Any arbitrary data you can send to Postback Received webhook. Max size is 1000 characters.
Metadata
Developer-defined metadata can be sent with any type of Message. They are delivered back in Message Echo webhook.
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"any": "arbitrary data"
}
}Reserved metadata keywords
platform_metadata - Metadata to be sent directly to Viber API, see Platform Metadata below.
Viber API has its own concept of metadata. It's called tracking_data. You can send tracking data as a string with any message, see Viber API documentation. Amio API reserves platform_metadata keyword to be mapped to original Viber tracking_data attribute.
You can use platform_metadata attribute to send tracking data directly to Viber API. This allows you to track messages and user’s replies. Tracking data are received back as metadata.platform_metadata attribute with message replies from the user.
{
"channel": { },
"contact": { },
"content": { },
"metadata": {
"platform_metadata": "these data are going to be sent directly to Viber API as tracking_data attribute"
}
}platform_metadata
string
Platform specific metadata to be sent directly to Viber API as a tracking_data attribute, see Viber API documentation. Max size 4000 characters.
List Channels
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: viber.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
viber
object
Represents a Viber public account connected to the channel. You can send and receive message only If Viber is connected.
viber.name
string
Name of the Viber Bot account.
viber.category
string
Viber public account category.
viber.access_token
string
Viber Bot account access token.
Get Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: viber.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
viber
object
Represents a Viber Bot account connected to the channel. You can send and receive message only If Viber is connected.
viber.name
string
Name of the Viber Bot account.
viber.category
string
Viber Bot account category.
viber.access_token
string
Viber Bot account access token.
Create Channel
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: viber.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
viber
object
Represents a Viber Bot account connected to the channel. You can send and receive message only If Viber is connected.
viber.name
string
Name of the Viber Bot account.
viber.category
string
Viber Bot account category.
viber.access_token
string
Viber Bot account access token.
Update Channel
Remove webhook
Set webhook attribute to null if you'd like to remove channel webhook.
id
string
Id of the channel.
type
string
Channel type specifying the underlying platform: viber.
name
string
Name of the channel.
webhook
object
Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.
webhook.id
string
Id of the webhook.
webhook.url
string
Webhook url.
webhook.secret
string
Secret token for securing received webhook calls, see Webhook Security for more details.
webhook.ssl_verification
string
Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.
viber
object
Represents a Viber Bot account connected to the channel. You can send and receive message only If Viber is connected.
viber.name
string
Name of the Viber Bot account.
viber.category
string
Viber Bot account category.
viber.access_token
string
Viber Bot account access token.
Contacts
Contact represents the Viber user. Contact is automatically created whenever you receive a message from the user for the first time.
List Contacts
id
string
Id of the contact. Id is unique across channels and is generated by Amio.
name
string
Name of the contact.
photo_url
string
Url to profile picture of the user.
Get Contact
id
string
Id of the contact. Id is unique across channels and is generated by Amio.
name
string
Name of the contact.
photo_url
string
Url to profile picture of the user.
Webhooks
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 Viber platform.
Message Received
This event is fired whenever a contact sends a message to your Viber Bot account.
Amio Persists Message Files
All incoming messages having a file url attachments (i.e. Image Message, Video Message , etc.) are persisted on Amio servers due to expiration reasons.
{
"event": "message_received",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"id": "6456078996108088196",
"channel": {
"id": "6456078759331238786",
"type": "viber"
},
"contact": {
"id": "6456078781510718339"
},
"content": {
"type": "text",
"payload": "That's really nice that I can write you here. You guys rock!"
},
"nlp": {}
}
}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.
Messages Delivered
This event notifies you of messages that were delivered to your contact.
{
"event": "messages_delivered",
"timestamp" : "2017-12-29T17:26:17.331Z",
"data" : {
"channel": {
"id": "6456078759331238786",
"type": "viber"
},
"contact": {
"id": "6456078781510718339"
},
"messages": [
{ "id": "6456078996108088196" },
{ "id": "6456079002382766981" }
],
"delivered_timestamp": "2017-12-29T17:26:16.001Z"
}
}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 when Amio servers received notification about message delivery. This value may vary from webhook timestamp attribute due to delays.
Messages Read
This event occurs when a message has been read by the contact.
{
"event": "messages_read",
"timestamp" : "2017-12-29T17:26:17.331Z",
"data" : {
"channel": {
"id": "6456078759331238786",
"type": "viber"
},
"contact": {
"id": "6456078781510718339"
},
"last_read_timestamp": "2017-12-29T17:26:27.346Z"
}
}data.channel
object
Channel where the data.contact resides in.
data.contact
object
Contact that has read messages delivered.
last_read_timestamp
string
All messages that were sent before this timestamp were read. (It doesn't mean "time when the messages were read".)
Message Failed
This event notifies you of a message that could not be delivered to the recipient. See Viber documentation for details.
{
"event": "message_failed",
"timestamp" : "2017-12-29T17:26:17.331Z",
"data" : {
"channel": {
"id": "6456078759331238786",
"type": "viber"
},
"contact": {
"id": "6456078781510718339"
},
"message": {
"id": "6456078996108088196"
},
"error": {
"code": 1,
"message": "Error while processing the request."
}
}
}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.
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.
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 any other channel with the same Viber Bot account.
{
"event": "message_echo",
"timestamp": "2016-10-06T13:42:48Z",
"data": {
"id": "6456078996108088196",
"channel": {
"id": "6456078759331238786",
"type": "viber"
},
"contact": {
"id": "6456078781510718339"
},
"content": {
"type": "text",
"payload": "We know, we try really hard to bring always something more to our beloved customers!"
},
"metadata": {
"any": "arbitrary data"
}
}
}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.
Postback Received
This callback occurs when the user presses Postback Button. You can use this event to perform certain action or to send a reply.
{
"event": "postback",
"timestamp": "2017-03-01T15:49:02.243Z",
"data": {
"channel": {
"id": "6456078759331238786",
"type": "viber"
},
"contact": {
"id": "6456078781510718339"