Amio Developer Hub

Welcome to Amio! Let's build on top of most reliable and full feature set API for messaging.

Get Started
Suggest Edits

Introduction

 

The Amio API unifies multiple messaging platforms under one REST API. Our API has resource-oriented URLs which is easy to predict. We also leverage HTTP response codes to indicate different errors. JSON is returned by all API endpoints including error responses.

Suggest Edits

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/messages
curl -X POST -H "Content-Type: application/json" https://amio.io/api/v1/messages?access_token={{OAUTH_TOKEN}}

Get Access Token

  1. Login to app.amio.io.
  2. Navigate to API settings.
  3. Copy the access token.
 

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.

HTTP Verb
Description

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.

Suggest Edits

Responses

 

HTTP status codes are used to communicate result of your request.

HTTP Status Code
Description

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.

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."
    }
  ]
}
Suggest Edits

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.

Request Parameter
Default Value
Description

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.

HTTP Response Header
Description

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=20
Suggest Edits

Rate Limiting

 

For security reasons, Amio API introduces rate limits:

  • maximum number of request you can do within an hour to 1000 requests
  • maximum opened connections to 50 simultaneously opened http connections to Amio servers

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: 1491820066
HTTP Response Header
Description

X-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"
    }
  ]
}
 

Run in Postman

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 the message types are supported by all channels. This chapter covers common message principles, see Channel Requests chapter for a complete list of message types available for each channel.

Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/{{channel_id}}/contacts/{{contact_id}}/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "{{MESSAGE_ID}}",
    "direction": "{{MESSAGE_DIRECTION}}",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "{{CHANNEL_ID}}",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "{{CONTACT_ID}}"
    },
    "content": {
      "payload": "{{CONTENT_TYPE}}",
      "type": "{{CONTENT_PAYLOAD}}"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

direction

string

Specifies if the message has been received or sent: received, sent.

sent

string

Iso 8601 Timestamp - time when the message was 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.

Suggest Edits

Send Message

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "{{CHANNEL_ID}}"
  },
  "contact": {
    "id": "{{CONTACT_ID}}"
  },
  "content": {
    "type": "{{CONTENT_TYPE}}",
    "payload": "{{CONTENT_PAYLOAD}}"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "{{MESSAGE_ID}}",
  "channel": {
    "id": "{{CHANNEL_ID}}",
    "type": "{{CHANNEL_TYPE}}"
  },
  "contact": {
    "id": "{{CONTACT_ID}}"
  },
  "content": {
    "type": "{{CONTENT_TYPE}}",
    "payload": "{{CONTENT_PAYLOAD}}"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to. You can get channel id in administration.

contact
object
contact.id
string
required

Id of the contact you wish to send the message to. There are different ways how to a contact (they are typically specific to a channel type), see Platform Specific Requests for more details.

content
object
content.type
string
required

Different types of the content can be sent: text, file, audio, video and image, structure, etc. See Platform Specific Requests for more detail.

content.payload
string
required

Payload is specific to message type. Different message types are documented in Platform Specific Requests.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

 

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"
  }
}
Suggest Edits

Notifications

 

Run in Postman

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.

Suggest Edits

Send Notification

 
posthttps://api.amio.io/v1/notifications
{
  "channel": {
    "id": "{{CHANNEL_ID}}",
  },
  "contact": {
    "id": "{{CONTACT_ID}}",
  },
  "type": "{{NOTIFICATION_TYPE}}"
}
A binary file was returned

You couldn't be authenticated

{
  "channel": {
    "id": "{{CHANNEL_ID}}",
    "type": "{{CHANNEL_TYPE}}"
  },
  "contact": {
    "id": "{{CONTACT_ID}}"
  },
  "type": "{{NOTIFICATION_TYPE}}"
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the notification to. You can get channel id in administration.

contact
object
contact.id
string
required

Id of the contact you wish to send the notification to. There are different ways how to a contact (they are typically specific to a channel type), see Platform Specific Requests for more details.

type
string
required

Type specifies the notification to be sent they are different in each platform, see Platform Specific Requests.

 

Response Body Params

 

Run in Postman

Channel represents a medium through which you can send and receive messages. There are different channel types (facebook_messenger, viber, etc.) what specifies the underlying platform.

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "{{CHANNEL_ID}}",
    "type": "{{CHANNEL_TYPE}}",
    "name": "{{CHANNEL_NAME}}",
    "webhook": {
      "id": "{{WEBHOOK_ID}}",
      "url": "{{WEBHOOK_URL}}",
      "secret": "{{SECRET}}",
      "ssl_verification": true
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger or 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.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/channel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/{{channel_id}}
A binary file was returned

You couldn't be authenticated

{
  "id": "{{CHANNEL_ID}}",
  "type": "{{CHANNEL_TYPE}}",
  "name": "{{CHANNEL_NAME}}",
  "webhook": {
    "id": "{{WEBHOOK_ID}}",
    "url": "{{WEBHOOK_URL}}",
    "secret": "{{SECRET}}",
    "ssl_verification": true
  }
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger or 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.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "{{CHANNEL_TYPE}}",
  "name": "{{CHANNEL_NAME}}",
  "webhook": {
  	"url": "{{WEBHOOK_URL}}"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "{{CHANNEL_ID}}",
  "type": "{{CHANNEL_TYPE}}",
  "name": "{{CHANNEL_NAME}}",
  "webhook": {
    "id": "{{WEBHOOK_ID}}",
    "url": "{{WEBHOOK_URL}}",
    "secret": "{{SECRET}}",
    "ssl_verification": true
  }
}

Body Params

type
string
required

Channel type, facebook_messenger or viber.

name
string

Name of the channel. If not set, it will be automatically filled with an account name of underlying platform.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger or 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.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "{{CHANNEL_NAME}}",
  "webhook": {
  	"url": "{{WEBHOOK_URL}}"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "{{CHANNEL_ID}}",
  "type": "{{CHANNEL_TYPE}}",
  "name": "{{CHANNEL_NAME}}",
  "webhook": {
    "id": "{{WEBHOOK_ID}}",
    "url": "{{WEBHOOK_URL}}",
    "secret": "{{SECRET}}",
    "ssl_verification": true
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: facebook_messenger or 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.

Remove webhook

Set webhook attribute to null if you'd like to remove channel webhook.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/{{channel_id}}
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

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 the contact is created (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.

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/{{channel_id}}/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "149277330380638",
    "name": "Dietrich Bonhoeffer"
  }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/{{channel_id}}/contacts/{{contact_id}}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "name": "Dietrich Bonhoeffer"
}

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/{{channel_id}}/contacts/{{contact_id}}
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact to be deleted.

 

Deleting a contact will also delete its conversation, messages and linked files.

 

Run in Postman

Settings resource is used for setting up certain properties of a channel like get started button, menu, etc.

Suggest Edits

Get Settings

 
gethttps://api.amio.io/v1/channels/channel_id/settings
curl --request GET \
  --url https://api.amio.io/v1/channels/{{channel_id}}/settings
A binary file was returned

You couldn't be authenticated

{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}

Path Params

channel_id
string
required

Id of the channel.

 
Suggest Edits

Update Settings

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}
A binary file was returned

You couldn't be authenticated

{
  {{PLATFORM_SPECIFIC_SETTINGS}}
}

Path Params

channel_id
string
required

Id of the channel.

 
Suggest Edits

Platform Specific Requests

 
 

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

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

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

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

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.

Suggest Edits

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": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!"
    }
  }
}
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.

Suggest Edits

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": "{{CHANNEL_ID}}",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "{{CONTACT_ID}}"
    },
    "messages": [
      { "id": "{{MESSAGE_ID}}" },
      { "id": "{{MESSAGE_ID}}" }
    ],
    "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.

Suggest Edits

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": "{{CHANNEL_ID}}",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "{{CONTACT_ID}}"
    },
    "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.

Suggest Edits

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.

 

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.

Suggest Edits

Facebook Messenger

 

Facebook Graph API

Amio uses Facebook Graph v2.9 version.

See Amio Documentation for getting started manuals and complete description of Facebook Messenger platform.

 

Run in Postman

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

{
  "contact": {  
    "id": "15234390803083474"
  },
  "channel": {...},
  "content": {...}
}

You receive contact.id when the user starts a conversation with you, see Entry Points for more details.

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": {...}
}

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.

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.

{
  "contact": {
    "user_ref": "{{YOUR_CUSTOM_USER_REF}}"
  },
  "channel": {...},
  "content": {...}
}
Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/151445772969853/contacts/149277330380638/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "149277330380638",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "151445772969853",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

direction

string

Specifies if the message has been received or sent: received, sent.

sent

string

Iso 8601 Timestamp - time when the message was 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

posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "4094732456547001"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent. Maximum size of 320 characters.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "4094732456547001"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to image.

content.payload
object
content.payload.url
string
required

Url of the image to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "audio",
    "payload": {
      "url": "http://dubioza.org/site/wp-content/uploads/2016/02/1.-All-Equal-feat-BEE2.mp3"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "4094732456547001"
  },
  "content": {
    "type": "audio",
    "payload": {
      "url": "http://dubioza.org/site/wp-content/uploads/2016/02/1.-All-Equal-feat-BEE2.mp3"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to audio.

content.payload
object
content.payload.url
string
required

Url of the audio to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "4094732456547001",
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to video.

content.payload
object
content.payload.url
string
required

Url of the video to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "file",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "4094732456547001"
  },
  "content": {
    "type": "file",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to file.

content.payload
object
content.payload.url
string
required

Url of the file to be sent.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
 

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
    }
  }
}
Parameter
Type
Description

content.type

string

Message type location.

content.payload.latitude

double

Location sent by user - latitude.

content.payload.longitude

double

Location sent by user -
longitude.

Suggest Edits

Receipt

Receipt type of message is suitable for sending order confirmation with all items listed, address and payment summary.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "receipt",
    "payload": {
      "order_id": "id546584", 
      "timestamp": "2016-10-06T13:42:48Z",
      "currency": "USD",
      "payment_method": "Visa ***8138.",
      "url_order": "http://petersapparel.parseapp.com/order?order_id=id546584",
      "shipping_address": {
        "name": "Tomáš Baťa",
        "address_line_1": "tř. Tomáše Bati 46",
        "address_line_2": "company Bata a.s.",
        "city": "Otrokovice",
        "postal_code": "765 02",
        "state": "Zlín Region",
        "country_code": "CZ"
      },
      "items": [ 
        {
          "title":"Winter Mens' Footware",
          "text":"100% Leather",
          "quantity":1,
          "price":67.5,
          "image_url":"http://3-cz-cdn.bata.eu/gallery/1/6/4/5/7/c.jpg"
        }
      ],
      "summary": {
        "shipping": 4.95,
        "tax": 6.19,
        "total": 78.64
      }
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "receipt",
    "payload": {
      "order_id": "id546584", 
      "timestamp": "2016-10-06T13:42:48Z",
      "currency": "USD",
      "payment_method": "Visa ***8138.",
      "url_order": "http://petersapparel.parseapp.com/order?order_id=id546584",
      "shipping_address": {
        "name": "Tomáš Baťa",
        "address_line_1": "tř. Tomáče Bati 46",
        "address_line_2": "company Bata a.s.",
        "city": "Otrokovice",
        "postal_code": "765 02",
        "country_code": "CZ"
      },
      "items": [ 
        {
          "title":"Winter Mens' Footware",
          "text":"100% Leather",
          "quantity":1,
          "price":67.5,
          "image_url":"http://3-cz-cdn.bata.eu/gallery/1/6/4/5/7/c.jpg"
        }
      ],
      "summary": {
        "shipping": 4.95,
        "tax": 6.19,
        "total": 78.64
      }
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to receipt.

content.quick_replies
array

Quick Replies enrich the message with buttons that are dismissed as soon as user taps one.

payload
object
payload.order_id
string
required

Order id. Has to be unique for each recepient.

payload.timestamp
date

Timestamp of the order. Must be in ISO 8601 timestamp form, e.g. 2016-10-06T13:42:48Z. This timestamp is zone agnostic it means that if you use zone in your format, the time will be shifted to UTC.

payload.currency
string
required

Currency in the form of ISO 4217, e.g. USD or CZK.

payload.url_order
string

URL with order details.

payload.payment_method
string
required

Payment method. This can be a custom string, e.g. Visa 1234.

shipping_address
object
shipping_address.name
string
required

Recipient's full name. Required if address is set.

shipping_address.address_line_1
string

Address line 1, P.O. box, company name, c/o. Required if city is set.

shipping_address.address_line_2
string

Apartment, suite, unit, building, floor, etc.

shipping_address.city
string

City. Required if address is set. Required if address_line_1is set.

shipping_address.postal_code
string

Postal Code. Required if address is set. Required if address_line_1is set.

shipping_address.state
string

State abbreviation or Region/Province (international). Required if address_line_1is set.

shipping_address.country_code
string

Country code according to ISO 3166 - alpha2. Required if address_line_1is set.

items
object
items.title
string

Item title. Required if item is set.

items.text
string

Item subtitle.

items.quantity
int32

Quantity of items.

items.price
double

Price of the item. 0 is allowed. Required if item is set.

items.image_url
string

Url of the item image.

summary
object
summary.shipping
double

Cost of shipping.

summary.tax
double

Total tax.

summary.total
double
required

Total cost.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
Facebook Messenger receipt.

Facebook Messenger receipt.

Receipt detail is shown when user taps on the receipt.

Receipt detail is shown when user taps on the receipt.

Suggest Edits

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.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string

Title of the message. Max size 80 characters. Title has to be specified with one more additional attribute: text, image_url or buttons. You can also omit the title attribute and use only text and buttons attributes.

payload.text
string

Message text. Max size 80 characters. However, you can use up to 640 characters if you use text with buttons only.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limetted to 3 buttons. See Buttons chapter for more details.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 

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

Suggest Edits

Structure - Horizontal Scroll

It is also possible to send multiple structured messages. They are displayed as a horizontal scroll within the Facebook Messenger.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
        "text": "9.5 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-1"
          }
        ]
      },
      {
        "title": "Beef burger with Coleslaw salad",
        "text": "12.0 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-2"
          }
        ]
      }
    ]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "title": "Leaf salad with smoked eggplant and zuchhini and dried tomatoes",
        "text": "9.5 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-1"
          }
        ]
      },
      {
        "title": "Beef burger with Coleslaw salad",
        "text": "12.0 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-2"
          }
        ]
      }
    ]
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string
required

Title of the message. Max size 80 characters. Title has to be specified with one more additional attribute: text, image_url or buttons.

payload.text
string

Message text. Max size 80 characters.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limetted to 3 buttons. See Buttons chapter for more details.

metadata
object

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
 

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

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"
  }
]
...
Parameter
Type
Description

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}}"
  }
]
...
Parameter
Type
Description

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

Call Button initiates a phone call.

...
buttons: [
  {
    "type": "phone",
    "title": "Call Us",
    "payload": "+420777111222"
  }
]
...
Parameter
Type
Description

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. Phone number has to be with leading '+' and country code, e.g. +420777123123 (See E.164 format).

Suggest Edits

Quick Replies

 

Quick Replies are buttons which provide a user with a set of pre-defined short replies that appear above the user input, making the keyboard less important. Each button also holds a developer-defined payload, which is invisible to the user but can be used for automated processing. When a button is tapped, the message is sent as a text, with the developer-defined payload in the callback. The buttons are dismissed as soon as user taps one.

Quick Replies can be attached to any Message type in the content.quick_replies attribute.

{
  "channel": { ... },
  "contact": { ... },
  "content": {
    "type": "...",
    "payload": "...",
    "quick_replies": [
      { "..." },
      { "..." },
      { "..." }
    ]
  }
}
Parameter
Type
Description

quick_replies

array of objects

Holds a list of maximally 11 objects of Text Quick Reply or User Quick Location Reply type.

Text Quick Reply

Text Quick Replies shows a button with text title and optionally a small image icon. When the user taps on the button, it fires Message Received webhook with 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"
  }
]
...
Parameter
Type
Description

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.

User Location Quick Reply

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"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to location.

 

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.

Platform Metadata

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"
  }
}
Parameter
Type
Description

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.

Facebook Messenger types are used to explicitly specify the purpose of a message and ensure that given message complies with Facebook policies. Amio uses default message type so you don't have to care about setting this attribute. However, you can specify a message type for advanced scenarios.

To send a message type, you can use type reserved keyword in metadata attribute:

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "type": "response"
  }
}
Parameter
Type
Description

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.

The basic Facebook App permission pages_messaging allows you to send messages within the 24 hours window after last message received from user plus 1 message outside this time frame, see Facebook App Permissions. Message tags give you the ability to send messages to the user outside of this timeframe. However, they should strictly comply with Facebook Messenger Platform Policy.

To send a message tag, you can use tag reserved keyword in metadata attribute:

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "tag": "shipping_update"
  }
}
Parameter
Type
Description

tag

string

Tag to be sent with message: account_update, application_update, appointment_update, community_alert, confirmed_event_reminder, feature_functionality_update, game_event, issue_resolution,
non_promotional_subscription, pairing_update, payment_update, personal_finance_update, reservation_update, shipping_update, ticket_update, transportation_update, see Facebook Documentation for full description. Tag can be set only if Types are not used.

Suggest a New Message Tag

You can contact us at support@amio.io. and we will ask Facebook to add new message tag.

Suggest Edits

Notifications

 

Run in Postman

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.

Suggest Edits

Send Notification

 
posthttps://api.amio.io/v1/notifications
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803083474"
  },
  "type": "typing_on"
}
A binary file was returned

You couldn't be authenticated

{
  "channel": {
    "id": "151445772969853",
  },
  "contact": {
    "id": "15234390803083474",
  },
  "type": "typing_on"
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the notification to. You can get channel id in administration.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

type
string
required

Type specifies the notification to be sent and can have following values:

messages_read - shows that all received messages from contact are read
typing_on - shows the typing indicator
typing_off - hides the typing indicator - if you don't switch off the typing indicator, it is switched off automatically (typically in 20 seconds).

 
Typing on notification sent.

Typing on notification sent.

 

Run in Postman

Channel represents a medium through which you can send and receive messages.

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "151445772969853",
    "type": "facebook_messenger",
    "name": "Amio",
    "webhook": {
      "id": "151017638112631",
      "url": "https://requestb.in/wjbibbwj",
      "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
      "ssl_verification": true
    },
    "facebook_page": {
      "id": "747722755375845",
      "name": "Amio",
      "category": "Internet Company",
      "access_token": "9mqyDMPBtgRG3{nWLYYh"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

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.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/channel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/151445772969853
A binary file was returned

You couldn't be authenticated

{
  "id": "151445772969853",
  "type": "facebook_messenger",
  "name": "Amio",
  "webhook": {
    "id": "151017638112631",
    "url": "https://requestb.in/wjbibbwj",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  },
  "facebook_page": {
    "id": "747722755375845",
    "name": "Amio",
    "category": "Internet Company",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
 

Response Body Params

Parameter
Type
Description

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.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "facebook_messenger",
  "name": "Amio Channel",
  "webhook": {
    "url": "https://requestb.in/wjbibbwj"
  },
  "facebook_page": {
    "id": "747722755375845",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "151445772969853",
  "type": "facebook_messenger",
  "name": "Amio Channel",
  "webhook": {
    "id": "151017638112631",
    "url": "https://requestb.in/wjbibbwj",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  },
  "facebook_page": {
    "id": "747722755375845",
    "name": "Amio",
    "category": "Internet Company",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}

Body Params

type
string
required

Channel type, facebook_messenger.

name
string

Name of the channel. If not set, it will be filled with connected Facebook Page name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

facebook_page
object
facebook_page.id
string
required

Id of the facebook page to be connected.

facebook_page.access_token
string
required

Access token to be used for Facebook API calls. This can be any type of access token with required permission. Typically, you will send User Access Token obtained after successful Facebook OAuth login procedure. When you create a channel, we request for long lived Page Access Token what ensures that the access token won't expire. See Facebook documentation for more details.

 

Response Body Params

Parameter
Type
Description

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.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Amio",
  "webhook": {
    "url": "https://requestb.in/wjbibbwj",
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "151445772969853",
  "type": "facebook_messenger",
  "name": "Amio",
  "webhook": {
    "id": "151017638112631",
    "url": "https://requestb.in/wjbibbwj",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  },
  "facebook_page": {
    "id": "747722755375845",
    "name": "Amio",
    "category": "Internet Company",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Might be an arbitrary name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Response Body Params

Parameter
Type
Description

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.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/{{channel_id}}
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

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

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/151445772969853/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "149277330380638",
    "name": "Dietrich Bonhoeffer",
    "gender": "male",
    "locale": "de",
    "time_zone": "+02:00",
    "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
  }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

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.

locale

string

User’s locale.

time_zone

string

Time zone set by the user.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/151445772969853/contacts/15234390803083474
A binary file was returned

You couldn't be authenticated

{
  "id": "15234390803083474",
  "phone_number": "+420123456789",
  "user_ref": "123456789",
  "name": "Dietrich Bonhoeffer",
  "gender": "male",
  "locale": "de",
  "time_zone": "+02:00",
  "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
  }

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

phone_number

string

Phone number of the contact. Only available if you previously wrote this contact using this 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 Checbox plugin works

name

string

Name of the contact.

gender

string

User's gender either male or female.

locale

string

User’s locale.

time_zone

string

Time zone set by the user.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/151445772969853/contacts/15234390803083474
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact to be deleted.

 
 

Run in Postman

Facebook Messenger allows you to set variety of items which enhance the feel and look of your Messenger channel for your users:

Suggest Edits

Get Settings

 
gethttps://api.amio.io/v1/channels/channel_id/settings
curl --request GET \
  --url https://api.amio.io/v1/channels/151445772969853/settings
A binary file was returned

You couldn't be authenticated

{
  "get_started_button": {...},
  "menu": {...},
  "user_input_enabled": ...,
  "domains_whitelist": [...]
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

get_started_button

object

Object specifying get started button properties, see Get Started Button.

menu

object

Menu for messenger thread, see Menu.

user_input_enabled

boolean

Enables or disables the user from sending a text message to you, see User Input enabled.

domains_whitelist

array

Some Facebook Messenger features needs to have used domains whitelisted, see Domains Whitelist.

Suggest Edits

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 on conversation start.

Get started button on conversation start.

Suggest Edits

Create/Update

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  }
}  
A binary file was returned

You couldn't be authenticated

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  }
}  

Path Params

channel_id
string
required

Id of the channel.

Body Params

get_started_button
object
get_started_button.payload
string

Any arbitrary data you will receive in Postback Received webhook when user clicks the button.

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "get_started_button": null
}  
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

 

Creating a menu in Facebook Messenger, you can highlight important actions or provide link to a webpage. Menu for Facebook Messenger is hierarchical and consists of different menu item types:

  • Url
  • Postback
  • Nested Menu

Menu requires Get Started Button

You must set a Get Started Button if you want to use menu in Facebook Messenger.

Menu in Facebook Messenger.

Menu in Facebook Messenger.

Suggest Edits

Create/Update

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "menu": { 
    "payload": {
      "menu_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": {
            "menu_items": [
              {
                "type": "url",
                "title": "NESTED URL Item",
                "payload": "http://www.google.com"
              },
              {
                "type": "postback",
                "title": "NESTED POSTBACK Item",
                "payload": "POSTBACK DATA"
              }
            ]
          }
        }
      ]
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "menu": { 
    "payload": {
      "menu_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": {
            "menu_items": [
              {
                "type": "url",
                "title": "NESTED URL Item",
                "payload": "http://www.google.com"
              },
              {
                "type": "postback",
                "title": "NESTED POSTBACK Item",
                "payload": "POSTBACK DATA"
              }
            ]
          }
        }
      ]
    }
  }
}

Path Params

channel_id
string
required

Id of the channel.

Query Params

manu.payload.menu_items
array
required

Array of menu item objects, see below. Maximum allowed size is 3.

 

Response Body Params

Url Menu Item

Parameter
Type
Description

type

string

Must be set to url.

title

string

Title of the menu item. Maximum size of 30 characters.

payload

string

Must be a valid URL.

Postback Menu Item

Parameter
Type
Description

type

string

Must be set to postback.

title

string

Title of the menu item. Maximum size of 30 characters.

payload

string

This data will be sent back to Postback Received webhook. Maximum size of 1000 characters.

Nested Menu

Parameter
Type
Description

type

string

Must be set to menu. The maximal hierarchical depth is 3 levels.

title

string

Title of the menu item. Maximum size of 30 characters.

payload

object

Object with attribute menu_items holding an array of items (url, postback, menu). The maximum number of items is 5 objects.

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.

Menu is visible only if:

  • Facebook Messenger has a version 106 and above.
  • The attached Facebook page must be published.
Nested menu items.

Nested menu items.

patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  menu: null
}
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

 
Suggest Edits

User Input Enabled

 

You can disable the user from writing you a message back using user_input_enabled settings. This force to the user to use only buttons provided in structured messages or in menu.

User Input Enabled requires Menu

You must set a Menu if you want to disable user input.

Disabled user input.

Disabled user input.

patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "user_input_enabled": false
}  
A binary file was returned

You couldn't be authenticated

{
  "user_input_enabled": false
}  

Path Params

channel_id
boolean
required

Id of the channel.

Body Params

user_input_enabled
string
required

Set to false in order to disable the users' input.

 
Suggest Edits

Domains Whitelist

 

Some features like Checkbox Plugin require domains to be whitelisted.

Whitelisting in Facebook Page Settings

In addition to domains whitelist API, you can whitelist domains in Facebook Page administration:

  1. Click Settings in your Facebook Page.
  2. Click Messenger Platform on the left menu.
  3. Edit domains in Whitelisted Domains sectionn.
Suggest Edits

Create/Update

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "domains_whitelist": [
     "https://amio.io"
  ]
}  
A binary file was returned

You couldn't be authenticated

{
  "domains_whitelist": [
     "https://amio.io"
  ]
}  

Path Params

channel_id
boolean
required

Id of the channel.

Body Params

whitelisted_domains
array of strings
required

A list of domains to whitelist. All domains must be valid. Up to 50 domains allowed.

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "domains_whitelist": null
}  
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
boolean
required

Id of the channel.

 
 

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.

Suggest Edits

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": "149277330380638",
    "channel": {
      "id": "151445772969853",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!",
      "quick_reply": {
        "payload": "DEVELOPER_DEFINED_PAYLOAD"
      }
    }
  }
}
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.

Suggest Edits

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": "149277264991719",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474"
    },
    "messages": [
      { "id": "149277330380638" }, 
      { "id": "145665489660999" }
    ],
    "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.

Suggest Edits

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": "149277264991719",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474"
    },
    "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 sent before this timestamp were read. (It doesn't mean "time when the messages were read".)

Suggest Edits

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": "149277330380638",
    "channel": {
      "id": "151445772969853",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474"
    },
    "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.

Suggest Edits

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": "151445772969853",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474"
    },
    "postback": {
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

payload

string

Developer-defined data set in Postback Button or Get Started Button.

Opt-in webhook is fired for several actions and is generally meant for binding a user in your application. This webhook is fired when:

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": "151445772969853",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474"
    },
    "opt_in": {
      "type": "send_to_messenger",
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

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": "151445772969853",
      "type": "facebook_messenger"
    },
    "contact": {
      "user_ref": "{{YOUR_CUSTOM_USER_REF}}" // set on frontend checkbox plugin
    },
    "opt_in": {
      "type": "checkbox",
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

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.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": "151445772969853",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "15234390803083474",
      "phone_number": "+1 (555) 857-6309"
    },
    "opt_in": {
      "type": "phone_number"
    }
  }
}
Parameter
Type
Description

contact.phone_number

string

Phone number used in original send message request.

See Amio Documentation for getting started manuals and complete description.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify a Viber contact with one of the following attributes:

Viber Contact Id

{
  "contact": {  
    "id": "15234390803084587"
  },
  "channel": {...},
  "content": {...}
}

You receive contact.id when the user starts a conversation with you, see Entry Points for more details.

Viber Phone Number

You can send a message using a phone number you already have (See Phone Number Entry Point for more details).

Viber Service Messages vs Public Accounts

Sending messages using a phone number is technically done through Viber service messages. Therefore, you need a separate Amio channel for Viber Service Messages. There are also few distinctions to regular Viber Public Accounts:

  1. Asynchronous - sending a message using phone number is asynchronous.
  2. Message Types - Viber Service Messages allow to send only certain message types (text, structure and image). Other message types are not supported.
  3. Webhooks - due to asynchronicity of send message, you will receive additional webhook message failed in case given phone number is not assigned to any Viber account.
{
  "contact": {
    "phone_number": "+1 (555) 857-6309"
  },
  "channel": {...},
  "content": {...}
}
Suggest Edits

List Messages

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id/messages
curl --request GET \
  --url https://api.amio.io/v1/channels/151454470963967/contacts/15234390803084587/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "149277361330533",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "151454470963967",
      "type": "viber"
    },
    "contact": {
      "id": "15234390803084587"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the message.

direction

string

Specifies if the message has been received or sent: received, sent.

sent

string

Iso 8601 Timestamp - time when the message was 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

posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151454470963967"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277361330533",
  "channel": {
    "id": "151454470963967",
    "type": "viber"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent. Maximum size of 320 characters. Maximum size of 1000 characters in case of sending using phone number (see Phone Number Entry Point for more details).

 

Eligible for Viber Service Messages

posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151454470963967"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277361330533",
  "channel": {
    "id": "151454470963967",
    "type": "viber"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "image",
    "payload": {
      "url": "https://upload.wikimedia.org/wikipedia/commons/1/11/V%C3%A1clav_Havel_cut_out.jpg"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to image.

payload
object
payload.url
string
required

Url of the image to be sent.

 

Eligible for Viber Service Messages

posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151454470963967"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277361330533",
  "channel": {
    "id": "151454470963967",
    "type": "viber"
  },
  "contact": {
    "id": "15234390803084587",
  },
  "content": {
    "type": "video",
    "payload": {
      "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to video.

payload
object
payload.url
string
required

Url of the video to be sent.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151454470963967"
  },
  "contact": {
    "id": "15234390803084587"
  },
 "content": {
    "type": "file",
    "payload": {
      "url": "https://example.com/file.pdf"
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277361330533",
  "channel": {
    "id": "151454470963967",
    "type": "viber"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "file",
    "payload": {
      "url": "https://example.com/file.pdf"
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to file.

payload
object
payload.url
string
required

Url of the file to be sent.

 
Suggest Edits

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.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151454470963967"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "149277330380638",
  "channel": {
    "id": "151445772969853",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "structure",
    "payload": {
      "title": "Leaf salad",
      "text": "9.5 €",
      "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
      "item_url": "https://example.com/daily-menu",
      "buttons": [
        {
          "type": "url",
          "title": "Show Details",
          "payload": "https://example.com/daily-menu/food-1"
        }
      ]
    }
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string

Title of the message. 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 20 characters. 80 characters for Viber Service Messages, ellipsis is not supported.

payload.text
string

Message text. It is displayed on 3 lines if zero or one button is used or on one line if more buttons are used. There fit usually around 65 characters or 22 characters respectively. 900 characters for Viber Service Messages, text is wrapped to lines.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limetted to 3 buttons. See Buttons chapter for more details. Viber Service Messages allows only 1 button.

metadata
string

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 

Eligible for Viber Service Messages

Suggest Edits

Structure - Horizontal Scroll

It is also possible to send multiple structured messages. They are displayed as a horizontal scroll within the Viber app.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "151445772969853"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "title": "Leaf salad",
        "text": "9.5 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-1"
          }
        ]
      },
      {
        "title": "Beef burger",
        "text": "12.0 €",
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "buttons": [
          {
            "type": "url",
            "title": "Show Details",
            "payload": "https://example.com/daily-menu/food-2"
          }
        ]
      }
    ]
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "151577544462698",
  "channel": {
    "id": "151515343979291",
    "type": "viber"
  },
  "contact": {
    "id": "15234390803084587"
  },
  "content": {
    "type": "structure",
    "payload": [
      {
        "buttons": [
          {
            "payload": "https://example.com/daily-menu/food-1",
            "type": "url",
            "title": "Show Details"
          }
        ],
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/f/fa/Fish_-lunch.jpg",
        "item_url": "https://example.com/daily-menu",
        "text": "9.5 €",
        "title": "Leaf salad"
      },
      {
        "buttons": [
          {
            "payload": "https://example.com/daily-menu/food-2",
            "type": "url",
            "title": "Show Details"
          }
        ],
        "image_url": "https://upload.wikimedia.org/wikipedia/commons/9/9b/YOKOSUKA-NAVY-BURGER-TSUNAMI.JPG",
        "item_url": "https://example.com/daily-menu",
        "text": "12.0 €",
        "title": "Beef burger with Coleslaw salad"
      }
    ]
  }
}

Body Params

channel
object
channel.id
string
required

Id of the channel you wish to send the message to.

contact
object
contact.id
string
required

Id of the contact. Id is unique across channels and is generated by Amio.

content
object
content.type
string
required

Must be set to structure.

payload
object
payload.title
string

Title of the message. 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 20 characters.

payload.text
string

Message text. It is displayed on 3 lines if zero or one button is used or on one line if more buttons are used. There fit usually around 65 characters or 22 characters respectively.

payload.image_url
string

Url of an image to be displayed. Image ratio is 1.91:1.

payload.item_url
string

Url which is opened when the message is tapped.

payload.buttons
array

Buttons to be shown below the message. Limetted to 3 buttons. See Buttons chapter for more details.

metadata
string

Metadata allows you to send any arbitrary data with the message. They are delivered back with Message Echo webhook.

 
 

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

Url Button

The Url Button opens a browser with given address.

...
buttons: [
  {
    "type": "url",
    "title": "Freedom",
    "payload": "https://en.wikipedia.org/wiki/Liberty"
  }
]
...
Parameter
Type
Description

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.

Postback Button

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}}"
  }
]
...
Parameter
Type
Description

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.

 

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.

Platform Metadata

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"
  }
}
Parameter
Type
Description

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.

 

Run in Postman

Channel represents a medium through which you can send and receive messages.

Suggest Edits

List Channels

 
gethttps://api.amio.io/v1/channels
curl --request GET \
  --url https://api.amio.io/v1/channels
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "151454470963967",
    "type": "viber",
    "name": "Amio",
    "webhook": {
      "id": "151017638112631",
      "url": "https://requestb.in/wjbibbwj",
      "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
      "ssl_verification": true
    },
    "viber": {
      "name": "Amio",
      "category": "Companies, Brands & Products",
      "access_token": "46c9501a7eefc1ab"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

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 public account.

viber.category

string

Viber public account category.

viber.access_token

string

Viber public account access token.

Suggest Edits

Get Channel

 
gethttps://api.amio.io/v1/channels/chanel_id
curl --request GET \
  --url https://api.amio.io/v1/channels/151454470963967
A binary file was returned

You couldn't be authenticated

{
  "id": "151454470963967",
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "id": "151017638112631",
    "url": "https://requestb.in/wjbibbwj",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  },
  "viber": {
    "name": "Amio",
    "category": "Companies, Brands & Products",
    "access_token": "46c9501a7eefc1ab"
  }
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

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 public account.

viber.category

string

Viber public account category.

viber.access_token

string

Viber public account access token.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "url": "https://requestb.in/wjbibbwj",
  },
  "viber": {
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "151454470963967",
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "id": "151017638112631",
    "url": "https://requestb.in/wjbibbwj",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  },
  "viber": {
    "name": "Amio",
    "category": "Companies, Brands & Products",
    "access_token": "46c9501a7eefc1ab"
  }
}

Body Params

type
string
required

Channel type, viber.

name
string

Name of the channel. If not set, it will be filled with connected Viber Public Account name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

viber
object
viber.access_token
string
required

Viber public account access token. It has to be unique as Viber Public Account can be assigned only to one channel. You receive this token from Viber.

 

Response Body Params

Parameter
Type
Description

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 public account.

viber.category

string

Viber public account category.

viber.access_token

string

Viber public account access token.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "url": "https://requestb.in/wjbibbwj"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "151454470963967",
  "type": "viber",
  "name": "Amio",
  "webhook": {
    "id": "151017638112631",
    "url": "https://requestb.in/wjbibbwj",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  },
  "viber": {
    "name": "Amio",
    "category": "Companies, Brands & Products",
    "access_token": "46c9501a7eefc1ab"
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Might be an arbitrary name.

webhook
object
webhook.url
string

Webhook url where all channel events would be received.

 

Response Body Params

Parameter
Type
Description

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 public account.

viber.category

string

Viber public account category.

viber.access_token

string

Viber public account access token.

Remove webhook

Set webhook attribute to null if you'd like to remove channel webhook.

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/151454470963967
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel to be deleted.

 
 

Run in Postman

Contact represents the Viber 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 Viber user using phone number you already have).

Suggest Edits

List Contacts

 
gethttps://api.amio.io/v1/channels/channel_id/contacts
curl --request GET \
  --url https://api.amio.io/v1/channels/151454470963967/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "15234390803084587",
    "name": "Dietrich Bonhoeffer",
    "locale": "de",
    "country": "DE",
    "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
  }
]

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

locale

string

User’s locale.

country

string

2 letters country code - ISO ALPHA-2 Code.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Get Contact

 
gethttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request GET \
  --url https://api.amio.io/v1/channels/151454470963967/contacts/01234567890A=
A binary file was returned

You couldn't be authenticated

{
  "id": "15234390803084587",
  "name": "Dietrich Bonhoeffer",
  "locale": "de",
  "country": "DE",
  "photo_url": "https://scontent.xx.fbcdn.net/v/t1.0-1/541992_511761562179706_48931455_n.jpg?oh=1b30d9f950c70b19cf99ef8ea81a169e&oe=5A5108B3"
}

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the contact. Id is unique across channels and is generated by Amio.

name

string

Name of the contact.

locale

string

User’s locale.

country

string

2 letters country code - ISO ALPHA-2 Code.

photo_url

string

Url to profile picture of the user.

Suggest Edits

Delete Contact

 
deletehttps://api.amio.io/v1/channels/channel_id/contacts/contact_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/151454470963967/contacts/01234567890A=
A binary file was returned

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact to be deleted.

 
 

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.

Suggest Edits

Message Received

 

This event is fired whenever a contact sends a message to your Viber public 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": "149277361330533",
    "channel": {
      "id": "151454470963967",
      "type": "viber"
    },
    "contact": {
      "id": "15234390803084587"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!"
    }
  }
}
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.

Suggest Edits

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": "151454470963967",
      "type": "viber"
    },
    "contact": {
      "id": "15234390803084587"
    },
    "messages": [
      { "id": "151456816768977" }, 
      { "id": "151456839269349" }
    ],
    "delivered_timestamp": "2017-12-29T17:26:16.001Z"
  }
}
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 when Amio servers received notification about message delivery. This value may vary from webhook timestamp attribute due to delays.

Suggest Edits

Message Failed

 

This event notifies you of a message that could not be sent using phone number. This happens mostly when Viber account for a given phone number doesn't exist.

Only for Viber Service Messages

This webhook is received only for Viber Service Messages, see Phone Number Entry Point.

{
  "event": "message_failed",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "151454470963967",
      "type": "viber"
    },
    "contact": {
      "id": "15217933990261301",
      "phone_number": "+420606123456",
    },
    "message": {
      "id": "151456816768977"
    },
    "error": {
      "code": 3,
      "message": "Cannot find Viber user for given phone number."
    }
  }
}
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

Error Code
Reason

1

Error while processing the request.

2

Sending messages to this user is blocked.

3

Cannot find Viber user for given phone number.

4

Message failed to be delivered within 24 hours.

Suggest Edits

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": "151454470963967",
      "type": "viber"
    },
    "contact": {
      "id": "15234390803084587"
    },
    "last_read_timestamp": "2017-12-29T17:26:27.346Z"
  }
}
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 sent before this timestamp were read. (It doesn't mean "time when the messages were read".)

Suggest Edits

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 public account.

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "149277361330533",
    "channel": {
      "id": "151454470963967",
      "type": "viber"
    },
    "contact": {
      "id": "15234390803084587"
    },
    "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.

Suggest Edits

Postback Received

 

This callback occurs when the user presses Postback 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": "151454470963967",
      "type": "viber"
    },
    "contact": {
      "id": "15234390803084587"
    },
    "postback": {
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

payload

string

Developer-defined data set in Postback Button.