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.

Location Header

All responses with status code 201 Created contain Location header with actual location of newly created resource, i.e. Location: https://api.amio.io/v1/channels/{channel_id}.

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

 

Amio API has different rate limits for each pricing plan. We limit number of requests you can do within a hour. And number of simultaneous connections you can have opened to Amio servers.

Pricing Plan
Number of Requests
Simultaneous Connections

Free

1000

3

Developer

2000

10

Enterprise

custom

custom

You can check the returned HTTP headers of any API request to see your current rate limit status for maximum number of requests:

curl -i https://api.amio.io/v1/channels/{{channel_id}}

HTTP/1.1 200 OK
Date: Mon, 01 Jul 2013 17:27:06 GMT
Status: 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 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"
    }
  ]
}

Some resources use or return locale defining the language and region. The format is following {language ISO 639-1}_{region ISO 3166-2}, i.e. en_US for American english.

  • Language is defined in ISO 639-1.
  • Region represents country or subdivisions and is defined in 3166-2
 

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 message types are supported by all channels.

Following chapters highlight only API requests that are common for all platforms. See platform specific documentation for more details:

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": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "{{CONTENT_TYPE}}",
    "payload": "{{CONTENT_PAYLOAD}}"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "{{MESSAGE_ID}}",
  "channel": {
    "id": "6456078759331238786",
    "type": "{{CHANNEL_TYPE}}"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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.

Notifications are available only on some platforms. See platform specific documentation for more details:

Suggest Edits

Send Notification

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

You couldn't be authenticated

{
  "channel": {
    "id": "6456078759331238786",
    "type": "{{CHANNEL_TYPE}}"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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.).

Channel Modes

Channel Mode controls how messages sent through the channel are processed. Available Modes vary across platforms. Please refer to platform specific documentation for more details about supported Modes.

The default Mode for all platforms is production.

Mode
Supported Platforms
Description

Production

All

Send Message requests will be accepted and forwarded to the platform.

Test

Mobile, RCS Business Messages, Viber Business Messages

Send Message requests will be accepted but won't be processed any further. This allows for testing without having to worry about cost of the test messages.

Amio

Viber Business Messages

Send Message requests will be sent using common Amio Sender ID. Messages sent are not charged but number of messages sent is limited.

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": "6456078759331238786",
    "type": "{{CHANNEL_TYPE}}",
    "name": "Some Name",
    "mode": "production",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: amio_chat, facebook_messenger, mobile, rbm, viber, viber_business_messages.

name

string

Name of the channel.

mode

string

Mode 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/6456078759331238786
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "{{CHANNEL_TYPE}}",
  "name": "Some Name",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "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: amio_chat, facebook_messenger, mobile, rbm, viber, viber_business_messages.

name

string

Name of the channel.

mode

string

Mode 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": "Some Name",
  "mode": "production",
  "webhook": {
  	"url": "https://my-project.com/webhooks"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "{{CHANNEL_TYPE}}",
  "name": "Some Name",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  }
}

Body Params

type
string
required

Channel type: amio_chat, facebook_messenger, mobile, viber, viber_business_messages.

name
string

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

mode
string

Mode of the channel. Allowed values depends on the channel type.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: amio_chat, facebook_messenger, mobile, rbm, viber, viber_business_messages.

name

string

Name of the channel.

mode

string

Mode 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": "Some Name",
  "mode": "production",
  "webhook": {
  	"url": "https://my-project.com/webhooks"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "{{CHANNEL_TYPE}}",
  "name": "Some Name",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel.

mode
string

Mode of the channel. Allowed values depends on the channel type.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: amio_chat, facebook_messenger, mobile, rbm, viber, viber_business_messages.

name

string

Name of the channel.

mode

string

Mode 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/6456078759331238786
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 you can create the contact (i.e. for Mobile platform the user is created when you send a message to the given phone number).

Contact Merging

Amio doesn't implement any type of contact merging for one user on different platforms.

Suggest Edits

List Contacts

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

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "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/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "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/6456078759331238786/contacts/6456078781510718339
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.

Settings are available only on some channels:

Suggest Edits

Get Settings

 
gethttps://api.amio.io/v1/channels/channel_id/settings
curl --request GET \
  --url https://api.amio.io/v1/channels/6456078759331238786/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.

 
 

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": {
      "payload": "What's the weather today?",
      "type": "text"
    },
    "nlp": {
      "intents": [
        {
          "confidence": 0.99847021852548,
          "id": "weather"
        }
      ],
      "native_data": {...}
    },
  }
}
Parameter
Type
Description

data

object

Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body except for the nlp key (see below). This key will be present only for received text messages on channels with NLP integration connected.

Natural Language Processing (NLP)

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

Parameter
Type
Description

nlp.intents

array of objects

List of intents ordered by confidence score.

nlp.intents[].id

string

Name (or other unique identifier) of the intent.

nlp.intents[].confidence

number

Confidence score of the intent.

nlp.native_data

object

Full unmodified JSON response as returned by the NLP service. For more information, please refer to the documentation of the service:
Wit.ai
Watson

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": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "messages": [
      { "id": "6456078996108088196" },
      { "id": "6456079002382766981" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the messages were delivered.

data.messages

array of messages

Array of messages that were delivered. Every message will contain message.id. Depending on platform used, the message can contain other fields.

data.delivered_timestamp

string

Iso 8601 Timestamp. The time of message delivery to the user's device. This value may vary from webhook timestamp attribute if provided by the platform. If the platform doesn't provide this time, Amio uses time when the webhook came to our servers.

Suggest Edits

Message Failed

 

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

Only for Some Platforms

This webhook is used only by some platforms, i.e. by Viber, Mobile, etc.

{
  "event": "message_failed",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309",
    },
    "message": {
      "id": "6456078996108088196"
    },
    "error": {
      "code": 1,
      "message": "Error while processing the request."
    }
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the message was sent but not delivered.

data.message

object

Messages which was sent, will contain only message.id.

data.error.code

number

Error code, see errors below.

data.error.message

string

Detail message of an error, see errors below.

Errors

Error Code
Reason

1

Error while processing the request.

2

Sending messages to this user is blocked.

3

Cannot find user for given phone number.

4

Message failed to be delivered within 24 hours.

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": "6456078759331238786",
      "type": "{{CHANNEL_TYPE}}"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "last_read_timestamp": "2016-10-06T13:40:13Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact that has read messages delivered.

last_read_timestamp

string

Iso 8601 Timestamp

All messages before this timestamp were read.

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

Amio Chat (Beta)

 

Amio Chat is in Beta!

See Amio Documentation for getting started manuals and complete description of Amio Chat.

Amio Chat brings you the ability to easily create your own web chat. This API documentation describes how to manage Amio Chat channels and send messages to users. To implement your custom web chat, use Amio Chat SDK for Web.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify an Amio Chat contact id. You receive contact.id when the user starts a conversation with you, see Message Received webhook.

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/6456078759331248741/contacts/6456078781510715474/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108099701",
    "direction": "sent",
    "sent": "2019-03-27T13:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "content": {
      "type": "text",
      "payload": "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": "6456078759331248741"
  },
  "contact": {
    "id": "6456078781510715474"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108099701",
  "channel": {
    "id": "6456078759331248741",
    "type": "amio_chat"
  },
  "contact": {
    "id": "6456078781510715474"
  },
  "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 1000 characters.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331248741"
  },
  "contact": {
    "id": "6456078781510715474"
  },
  "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": "6456078996108099701",
  "channel": {
    "id": "6456078759331248741",
    "type": "amio_chat"
  },
  "contact": {
    "id": "6456078781510715474"
  },
  "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.

 
 

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": "6456078759331248741"
  },
  "contact": {
    "id": "6456078781510715474"
  },
  "type": "custom",
  "payload": {
    "any": "arbitrary data"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "channel": {
    "id": "6456078759331248741",
  },
  "contact": {
    "id": "6456078781510715474",
  },
  "type": "custom",
  "payload": {
    "any": "arbitrary data"
  }
}

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 - Notifies that all received messages from contact are read.
- typing_on - Notifies that the typing indicator should be shown.
- typing_off - Notifies that the typing indicator should be hidden.
- custom - Any arbitrary notification to be sent. This notification type can contain any arbitrary data sent in payload.

payload
object

Payload is used for custom notification type and can contain any arbitrary data.

 
 

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": "6456078996108099701",
    "type": "amio_chat",
    "name": "Amio Chat",
    "mode": "production",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: amio_chat.

name

string

Name of the channel.

mode

string

Mode 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/6456078996108099701
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108099701",
  "type": "amio_chat",
  "name": "Amio Chat",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  }
}
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: amio_chat.

name

string

Name of the channel.

mode

string

Mode 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": "amio_chat",
  "name": "Amio Chat",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108099701",
  "type": "amio_chat",
  "name": "Amio Chat",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "TsEW3ZmFKmpe2WltNfVmqtQie24",
    "ssl_verification": true
  }
}

Body Params

type
string
required

Channel type, amio_chat.

name
string

Name of the channel. If not set, it will generate one.

mode
string

Mode of the channel. Only production mode is allowed.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: amio_chat.

name

string

Name of the channel.

mode

string

Mode 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": "Amio",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331248741",
  "type": "amio_chat",
  "name": "Amio",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Can be an arbitrary name.

mode
string

Mode of the channel. Only production mode is allowed.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: amio_chat.

name

string

Name of the channel.

mode

string

Mode 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/6456078759331248741
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 Amio chat user. Contact is automatically created whenever you receive a message from the user for the first time.

Suggest Edits

List Contacts

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

You couldn't be authenticated

[
    {
        "id": "6456078781510715474",
        "name": "6456078781510715474"
    }
]

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. Id by default.

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/6456078759331248741/contacts/6456078781510715474
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510715474",
  "name": "6456078781510715474"
}

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. Id by default.

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/6456078759331248741/contacts/6456078781510715474
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

Amio Chat allows you to restrict domains where the chat will be running, using a domain whitelist.

Suggest Edits

Get Settings

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

You couldn't be authenticated

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

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

domains_whitelist

array

List of domains allowed for cross origin requests (CORS) during connection to Amio Chat servers.

Suggest Edits

Update Settings

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

You couldn't be authenticated

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

Path Params

channel_id
string
required

Id of the channel.

 

Delete Settings

You can delete any settings with PATCH request setting the parameter to null, i.e. {"domains_whitelist": null}.

Response Body Params

Parameter
Type
Description

domains_whitelist

array

List of domains allowed for cross origin requests (CORS) during connection to Amio Chat servers. If this value is set to null or an empty list, then all connection attempts will be refused.

Suggest Edits

Domains Whitelist

 

Amio Chat allows to restrict domains where the web chat will be running. Only the whitelisted domains will be allowed for cross origin requests (CORS) during connection to Amio Chat servers.

When adding domains to the whitelist, please keep in mind that the whole fully qualified domain name, including protocol, is required. If your server uses non-standard port, then you have to include it, too (standard ports are 80 for HTTP, 443 for HTTPS). localhost is allowed and has to be whitelisted if you want to run your code locally.

If the domain whitelist is set to null or an empty list [ ], then no connection will be allowed.

Default domain whitelist value is null which means that no connection will be allowed.

 

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

Suggest Edits

Message Received

 

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

{
  "event": "message_received",
  "timestamp": "2019-03-27T18:42:48Z",
  "data": {
    "id": "6456078996108099701",
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!"
    },
    "nlp": {...}
  }
}
Parameter
Type
Description

data

object

Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

data.nlp

object

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": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "messages": [
      { "id": "6456078996108099701" }, 
      { "id": "6456078996108097880" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the messages were delivered.

data.messages

array

Array of messages that were delivered. Every message will contain message.id.

data.delivered_timestamp

string

Iso 8601 Timestamp. The time of message delivery to the user's device. This value may vary from webhook timestamp attribute due to delays.

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": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "last_read_timestamp": "2016-10-06T13:40:13Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact that has read messages delivered.

last_read_timestamp

string

Iso 8601 Timestamp

All messages that were delivered before this timestamp were read. (It doesn't mean "time when the messages were read".)

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.

{
  "event": "message_echo",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108099701",
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
Parameter
Type
Description

data

object

Object representing message which is echoed. Different type of messages can be received (text, image, etc.). The structure matches Send Message response body.

Suggest Edits

Notification Received

 

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

{
  "event": "notification",
  "timestamp": "2019-03-28T12:36:34.873Z",
  "data": {
    "channel": {
      "id": "6456078759331248741",
      "type": "amio_chat"
    },
    "contact": {
      "id": "6456078781510715474"
    },
    "type": "custom",
    "payload": {
      "any": "arbitrary data"
    }
  }
}
Parameter
Type
Description

data

object

Object representing notification received. Only custom notification is supported from client side, see Send Notification for more details.

Suggest Edits

Facebook Messenger

 

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

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

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

Phone Number

You can send a message using a phone number you already have (see Phone Number Entry Point for more details). Attributes first_name and last_name are optional and just help to match the phone number with an existing Facebook User.

{
  "contact": {
    "phone_number": "+1 (555) 857-6309",
    "first_name": "Anthony",
    "last_name": "Hopkins"
  },
  "channel": {...},
  "content": {...}
}
{
  "id": "...",
  "contact": {
    "id": "15234390803083474",
    "phone_number": "15558576309"
  },
  "channel": {...},
  "content": {...}
}

Opt-in and Messages Delivered Webhooks

When you send a message using phone number, you can listen to Opt-in Webhook which is fired when the user confirms your request. You should however also listen to Messages Delivered Webhook which is fired for any further message sent after the user opts in.

Phone Number Format

Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.

Message Tags

Facebook requires you to comply with subscription messages policy when sending messages using phone number. This applies for all messages sent before the user opts in to receive messages from you.

Therefore, when you send messages before the opt-in, Amio automatically sets tag non_promotional_subscription (see tags) to your messages. You can set appropriate message tag which will be used after the user opts in (i.e. shipping_update).

User Ref

Opt-in Webhook delivers a user_ref attribute which can be used for sending the first message to the user.

{
  "contact": {
    "user_ref": "{{YOUR_CUSTOM_USER_REF}}"
  },
  "channel": {...},
  "content": {...}
}
{
  "id": "...",
  "contact": {
    "id": "15234390803083474",
    "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/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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 640 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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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. Max size is 25 MB.

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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339",
  },
  "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. Max size is 25 MB.

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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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. Max size is 25 MB.

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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "facebook_messenger"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "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": "+1 (555) 857-6309"
  }
]
...
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. Make sure the phone number is in international format.

Suggest Edits

Quick Replies

 

Quick Replies are buttons with a set of pre-defined short replies that appear above the user input, making the keyboard less important. When a button is tapped, the message is sent as a text and you'll receive it to your webhook. The buttons are dismissed as soon as user taps one or reply with own text.

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

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

quick_replies

array of objects

Holds a list of maximally 11 objects of Text Quick Reply, User Location Quick Reply, Email Quick Reply or Phone Number Quick Reply type.

Text Quick Reply

Text Quick Replies show buttons with text and optionally a small image icon. Each button can also hold a developer-defined payload, which is invisible to the user but can be used for automated processing. When the user taps on the button, it fires Message Received webhook with text and developer payload if specified.

...
"quick_replies": [
  {
    "type": "text",
    "title": "Pilsner Urquell",
    "payload": "DEVELOPER_DEFINED_PAYLOAD",
    "image_url": "http://www.logotypes101.com/logos/778/70D1EF7E13BFAC232F2D05DE2E5594E0/pubisc.png"
  },
  {
    "type": "text",
    "title": "Heineken",
    "payload": "DEVELOPER_DEFINED_PAYLOAD",
    "image_url": "http://www.logotypes101.com/free_vector_logo_png/33082/85D3F063102F2476DC36D26D4D7A15C1/Heineken29"
  }
]
...
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.

Email Quick Reply

Email can also be requested using a quick reply. If the user has an email set in the profile, then it will be pre-filed as a quick reply button. When the user taps on the button, it fires Message Received webhook with text containing his email address.

...
"quick_replies": [
  {
    "type": "email"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to email.

Phone Number Quick Reply

Phone number quick reply allows you to easily ask for users' phone number. If the user has a phone number set in the profile, then it will be pre-filed as a quick reply button. When the user taps on the button, it fires Message Received webhook with text containing his phone number.

...
"quick_replies": [
  {
    "type": "phone_number"
  }
]
...
Parameter
Type
Description

type*

string

Must be set to phone_number.

 

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 handles message types automatically so you don't have to care about setting this attribute. However, you can specify a message type for custom scenarios.

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

{
  "channel": { ... },
  "contact": { ... },
  "content": { ... },
  "metadata": {
    "type": "response"
  }
}
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.

Message tags give you the permission to send messages within and beyond the 24-hour standard messaging window. 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": "6456078759331238786"
  },
  "contact": {
    "id": "6456078781510718339"
  },
  "type": "typing_on"
}
A binary file was returned

You couldn't be authenticated

{
  "channel": {
    "id": "6456078759331238786",
  },
  "contact": {
    "id": "6456078781510718339",
  },
  "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": "6456078759331238786",
    "type": "facebook_messenger",
    "name": "Amio",
    "mode": "production",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "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.

mode

string

Mode 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/6456078759331238786
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "facebook_messenger",
  "name": "Amio",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "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.

mode

string

Mode 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",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "facebook_page": {
    "id": "747722755375845",
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "facebook_messenger",
  "name": "Amio Channel",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "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.

mode
string

Mode of the channel. Only production mode is allowed.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

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.

You can only use access tokens that were generated for a certain Facebook App. If you want to use your own Facebook App, let us know at support@amio.io. This SO answer explains how to generate access_token for a given Facebook Application.

 

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.

mode

string

Mode of the channel.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

facebook_page

object

Id of the connected page.

facebook_page.name

string

Name of the facebook page.

facebook_page.category

string

Category of the facebook page.

facebook_page.access_token

string

Long or short lived facebook page access token with required permission.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Amio",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks",
  },
  "facebook_page": {
    "access_token": "9mqyDMPBtgRG3{nWLYYh"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "facebook_messenger",
  "name": "Amio",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "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.

mode
string

Mode of the channel. Only production mode is allowed.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

facebook_page
object
facebook_page.access_token
string

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.

You can only use access tokens that were generated for a certain Facebook App. If you want to use your own Facebook App, let us know at support@amio.io. This SO answer explains how to generate access_token for a given Facebook Application.

 

Remove webhook

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

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.

mode

string

Mode 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

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786
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/6456078759331238786/contacts
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "name": "Dietrich Bonhoeffer",
    "gender": "male",
    "locale": "de_DE",
    "time_zone": "+02:00",
    "photo_url": "https://storage.amio.io/profile/6456078781510718339/avatar"
  }
]

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 in standard format.

time_zone

string

Time zone set by the user.

photo_url

string

Url to profile picture of the user. Profile picture is uploaded to Amio servers the first time the user details are requested.

This request can take long time to process due to the need to query Facebook for profile pictures and upload them to Amio servers (especially if the list of contacts is long and we need to process the profile picture of all of them).

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/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "phone_number": "15558576309",
  "user_ref": "123456789",
  "name": "Dietrich Bonhoeffer",
  "gender": "male",
  "locale": "de_DE",
  "time_zone": "+02:00",
  "photo_url": "https://storage.amio.io/profile/6456078781510718339/avatar"
  }

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 (E.164 format). Only available if you have previously sent a message to this contact using a phone number. For more details see Using phone number.

user_ref

string

User_ref instead of id until you get a real id. For more details have a look at how Checkbox plugin works

name

string

Name of the contact.

gender

string

User's gender either male or female.

locale

string

User’s locale in standard format.

time_zone

string

Time zone set by the user.

photo_url

string

Url to profile picture of the user. Profile picture is uploaded to Amio servers the first time the user details are requested.

First request for contact's details can take long time to process due to the need to query Facebook for profile picture and upload it to Amio servers.

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/6456078759331238786/contacts/6456078781510718339
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 a variety of items which enhance the feel and look of your Messenger channel for your users:

Facebook API Rate Limits

All settings requests directly interact with Facebook API. Unlike other Facebook API endpoints, this endpoint has low rate limits. Amio API will inform you when Facebook API rate limits are reached. It usually takes several minutes until Facebook resets the rate limits.

Suggest Edits

Get Settings

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

You couldn't be authenticated

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  },
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        }
      ]
    }
  ],
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ],
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Path Params

channel_id
string
required

Id of the channel.

 

Response Body Params

Parameter
Type
Description

get_started_button

object

Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.

get_started_button.payload

string

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

menu

array

List of the menu for different locales. Given the menu is displayed based on the user's locale preference. If you want to set the menu, get started button is required as well. When setting a menu, at least one default locale menu is required. See Menu chapter for more details.

menu.[ ].locale

string

Specifies locale of given menu. Value has to be in form of locale or default.

menu.[ ].items

object

List of menu item objects. Maximum allowed size is 3.

user_inputs

array

List of settings for user inputs for different locales. If you want to disable user inputs then the menu is required to be set. When setting user input, at least one default locale user input is required. See User Inputs chapter for more details.

user_inputs.[ ].locale

string

Specifies locale of given user input. Value has to be in form of locale or default.

user_inputs.[ ].enabled

boolean

Set to false in order to disable users' input, set to true otherwise.

domains_whitelist

array

Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.

Suggest Edits

Update Settings

 
patchhttps://api.amio.io/v1/channels/channel_id/settings
{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  },
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        }
      ]
    }
  ],
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ],
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}
A binary file was returned

You couldn't be authenticated

{
  "get_started_button": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  },
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com"
        }
      ]
    }
  ],
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ],
  "domains_whitelist": [
    "https://app.amio.io"
  ]
}

Path Params

channel_id
string
required

Id of the channel.

 

Delete Settings

You can delete any settings with PATCH request setting the parameter to null, i.e. {"menu": null}.

Response Body Params

Parameter
Type
Description

get_started_button

object

Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.

get_started_button.payload

string

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

menu

array

List of the menu for different locales. Given the menu is displayed based on the user's locale preference. If you want to set the menu, get started button is required as well. When setting a menu, at least one default locale menu is required. See Menu chapter for more details.

menu[].locale

string

Specifies locale of given menu. Value has to be in form of locale or default.

menu[].items

array[object]

List of menu item objects. Maximum allowed size is 3.

user_inputs

array[object]

List of settings for user inputs for different locales. If you want to disable user inputs then the menu is required to be set. When setting user input, at least one default locale user input is required. See User Inputs chapter for more details.

user_inputs[].locale

string

Specifies locale of given user input. Value has to be in form of locale or default.

user_inputs[].enabled

boolean

Set to false in order to disable users' input, set to true otherwise.

domains_whitelist

array[string]

Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.

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": {
    "payload": "{{GET_STARTED_PAYLOAD}}"
  } 
}
Parameter
Type
Description

get_started_button

object

Get started button is visible on the welcome screen when the user comes for the first time. See Get Started Button chapter for more details.

get_started_button.payload

string

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

Get started button on conversation start.

Get started button on conversation start.

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

The Menu requires Get Started Button

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

Testing Tips

Facebook Messenger menu is cached by default. If you update the menu while testing just refresh the page. If it doesn't help, try refreshing the web. If it doesn't help, try deleting the messenger thread and then beginning the conversation once again.

The Menu is visible only if:

  • Facebook Messenger has a version 106 and above.
  • The attached Facebook page must be published.
{
  "menu": [
    {
      "locale": "default",
      "items": [
        {
          "type": "url",
          "title": "URL Item",
          "payload": "http://www.google.com/"
        },
        {
          "type": "postback",
          "title": "POSTBACK Item",
          "payload": "POSTBACK DATA"
        },
        {
          "type": "menu",
          "title": "NESTED Item",
          "payload": {
            "items": [
              {
                "type": "url",
                "title": "NESTED URL Item",
                "payload": "http://www.google.com/"
              }
            ]
          }
        }
      ]
    }
  ]
}
Parameter
Type
Description

menu[].locale

string

Specifies locale of given menu. Value has to be in form of locale or default.

menu[].items

array[object]

List of menu item objects. Maximum allowed size is 3.

Url Menu Item

Parameter
Type
Description

type

string

Must be set to url.

title

string

Title of the menu item. A maximum size of 30 characters.

payload

string

Must be a valid URL.

Postback Menu Item

Parameter
Type
Description

type

string

Must be set to postback.

title

string

Title of the menu item. A maximum size of 30 characters.

payload

string

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

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. A maximum size of 30 characters.

payload

object

Object with attribute items holding an array of nested menu items.

The maximum number of items is 5 objects.

Menu can have a deep nesting up to level of 3.

Menu in Facebook Messenger.

Menu in Facebook Messenger.

Nested menu items.

Nested menu items.

Suggest Edits

User Inputs

 

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

{
  "user_inputs": [
    {
      "locale": "default",
      "enabled": true
    }
  ]
}
Parameter
Type
Description

user_inputs[].locale

string

Specifies locale of given menu. Value has to be in form of locale or default.

user_inputs[].enabled

boolean

Set to false in order to disable users' input, set to true otherwise.

User Inputs requires Menu

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

Disabled user input.

Disabled user input.

Suggest Edits

Domains Whitelist

 

Some features like Checkbox Plugin require domains to be whitelisted.

{
  "domains_whitelist": [
    "https://app.amio.io"
  ] 
}
Parameter
Type
Description

domains_whitelist

array[string]

Some Facebook Messenger features needs to have used domains whitelisted. See Domains Whitelist chapter for more details.

Whitelisting in Facebook Page Settings

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

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

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": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!",
      "quick_reply": {
        "payload": "DEVELOPER_DEFINED_PAYLOAD"
      }
    },
    "nlp": {...}
  }
}
Parameter
Type
Description

data

object

Object representing message received. Different type of messages can be received (text, image, etc.). The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

data.nlp

object

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": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "messages": [
      { "id": "6456078996108088196" }, 
      { "id": "6456079002382766981" }
    ],
    "delivered_timestamp": "2016-10-06T13:40:01Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact to whom the messages were delivered.

data.messages

array

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": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "last_read_timestamp": "2016-10-06T13:40:13Z"
  }
}
Parameter
Type
Description

data.channel

object

Channel where the data.contact resides in.

data.contact

object

Contact that has read messages delivered.

last_read_timestamp

string

Iso 8601 Timestamp

All messages 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": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our beloved customers!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
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": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "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": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "opt_in": {
      "type": "send_to_messenger",
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
Parameter
Type
Description

opt_in.type

string

Describes what type of opt-in this is. In case of Send to Messenger, this will always be send_to_messenger.

opt_in.payload

string

Data set in Send to Messenger Button as data-ref attribute.

Opt-in for Checkbox

When user ticks Checkbox plugin, you will receive following webhook.

{
  "event": "opt_in",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339",
      "user_ref": "{{YOUR_CUSTOM_USER_REF}}" // set on frontend checkbox plugin
    },
    "opt_in": {
      "type": "checkbox",
      "payload": "{{PASS_THROUGH_PARAM}}"
    }
  }
}
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.type

string

Describes what type of opt-in this is. In case of Checkbox plugin, this will always be checkbox.

opt_in.payload

string

Data that has been set in checkbox plugin ref attribute.

Opt-in for Phone Number Matching

This webhook is sent when a user accepts the message request sent to his phone number using Phone Number Entry Point.

{
  "event": "opt_in",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "channel": {
      "id": "6456078759331238786",
      "type": "facebook_messenger"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "opt_in": {
      "type": "phone_number"
    }
  }
}
Parameter
Type
Description

contact.phone_number

string

Phone number in E.164 format.

opt_in.type

string

Describes what type of opt-in this is. In case of Phone Number Matching, this will always be phone_number.

Mobile channel is primarily used for SMS send and receive. Amio integrates with 3rd party providers which you can connect in administration and use Amio API to send messages.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify a Mobile contact with a phone number you already have.

{
  "contact": {  
    "id": "+1 (555) 857-6309"
  },
  "channel": {...},
  "content": {...}
}
{
  "id": "...",
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "channel": {...},
  "content": {...}
}

Phone Number Format

Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.

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/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "mobile"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "phone_number": "+1 (555) 857-6309"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "mobile"
  },
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "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. phone_number
string
required

Phone number of the contact. All phone number formats are accepted.

⚠ You always need to include international call prefix.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent. Maximum length of text depends on provider (MessageBird - 1377 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"
  }
}
 

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": "6456078759331238786",
    "type": "mobile",
    "name": "Amio Mobile",
    "mode": "production",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    },
    "provider": {
      "type": "messagebird",
      "sender_id": "phonenumber",
      "access_token": "r3TniW2smgLGE3ntqHT",
      "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
      "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152775927128158",
      "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: mobile.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent as SMS.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message as SMS.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider to be used as a sender number. Any string in case of using shared number.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Suggest Edits

Get Channel

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

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "mobile",
  "name": "Amio Mobile",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
    "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152775927128158",
    "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
  }
}

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: mobile.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent as SMS.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message as SMS.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider to be used as a sender number. Any string in case of using shared number.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "mobile",
  "name": "Amio Mobile",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "mobile",
  "name": "Amio Mobile",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
    "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152776172104684",
    "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
  }
}

Body Params

type
string
required

Channel type, mobile.

name
string

Name of the channel. If not set, it will be auto-generated.

mode
string

Mode of the channel. production - Send Message requests will be accepted and sent as SMS. test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message as SMS.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

provider
object
provider.type
string
required

Name of the service provider. Following values are allowed: messagebird.

provider.access_token
string
required

Access token used for authorising requests to provider.

provider.signing_key
string
required

Signature key used for verifying that incoming webhook came from MessageBird. You can get this key in MessageBird administration.

provider.sender_id
string
required

Phone number registered at the provider or custom sender ID to be used as a message originator.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: mobile.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent as SMS.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message as SMS.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider or custom sender ID to be used as a message originator.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "name": "Amio",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "provider": {
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078759331238786",
  "type": "mobile",
  "name": "Amio",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "provider": {
    "type": "messagebird",
    "sender_id": "phonenumber",
    "access_token": "r3TniW2smgLGE3ntqHT",
    "signing_key": "GDVCrN9tgECUrkouzh4gyn7k",
    "status_webhook_url": "https://api.amio.io/webhook/messagebird/status/152775927128158",
    "receive_webhook_url": "https://api.amio.io/webhook/messagebird/message/6204630442/152811200579929"
  }
}

Path Params

channel_id
string
required

Id of the channel.

Body Params

name
string

Name of the channel. Might be an arbitrary name.

mode
string

Mode of the channel. production - Send Message requests will be accepted and sent as SMS. test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message as SMS.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

provider
object
provider.access_token
string

Access token used for authorising requests to provider.

provider.signing_key
string

Signature key used for verifying that incoming webhook came from MessageBird. You can get this key in MessageBird administration.

provider.sender_id
string

Phone number registered at the provider or custom sender ID to be used as a message originator.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: mobile.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent as SMS.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message as SMS.

webhook

object

Webhook object specifies the entry point to which all events are delivered. It is null if there is no webhook set. See Webhooks for more details.

webhook.id

string

Id of the webhook.

webhook.url

string

Webhook url.

webhook.secret

string

Secret token for securing received webhook calls, see Webhook Security for more details.

webhook.ssl_verification

string

Specifies whether to verify SSL certificates or not. Setting this option to false is not recommended.

provider

object

Represents a provider used to receive and deliver messages.

provider.type

string

Name of the service provider: messagebird.

provider.sender_id

string

Phone number registered at the provider or custom sender ID to be used as a message originator.

provider.access_token

string

Access token used for authorising requests to provider.

provider.signing_key

string

Signature key used for verifying that incoming webhook came from MessageBird.

provider.status_webhook_url

string

Amio webhook url to be used by provider to deliver notifications like message delivered, message failed, etc.

provider.receive_webhook_url

string

Amio webhook url to be used by provider to deliver incoming SMS messages.

Remove webhook

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

Suggest Edits

Delete Channel

 
deletehttps://api.amio.io/v1/channels/channel_id
curl --request DELETE \
  --url https://api.amio.io/v1/channels/6456078759331238786
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 mobile number owner. Contact is automatically created whenever you send a message to a new phone number or when you receive a message from the user.

Suggest Edits

List Contacts

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

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "name": "15558576309",
    "phone_number": "15558576309"
  }
]

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. Phone number by default.

phone_number

string

Phone number of the contact (E.164 format).

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/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "name": "15558576309",
  "phone_number": "15558576309"
}

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. Phone number by default.

phone_number

string

Phone number of the contact (E.164 format).

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/6456078759331238786/contacts/6456078781510718339
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.

Suggest Edits

Message Received

 

This event is fired whenever a contact sends a message to your dedicated phone number or replies to you in case of shared number.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "mobile"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you back. You guys rock!"
    },
    "nlp": {...}
  }
}
Parameter
Type
Description

data

object

Object representing message received. The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

data.nlp

object

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": "6456078759331238786",
      "type": "mobile"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "messages": [
      { "id": "6456078996108088196" }
    ],
    "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. This may happen when given phone number is wrong or when message send expires.

{
  "event": "message_failed",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "channel": {
      "id": "1527759271281586456078759331238786",
      "type": "mobile"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "message": {
      "id": "6456078996108088196"
    },
    "error": {
      "code": 1,
      "message": "Error while processing the request."
    }
  }
}
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.

4

Message failed to be delivered within 24 hours.

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.

{
  "event": "message_echo",
  "timestamp" : "2017-12-29T17:26:17.331Z",
  "data" : {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "mobile"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "type": "text",
      "payload": "We know, we try really hard to bring always something more to our great users!"
    },
    "metadata": {
      "any": "arbitrary data"
    }
  }
}
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

RCS Business Messages

 

RCS Business Messages (RBM) is brought to us by Google and takes advantage of the RCS communication protocol which will eventually replace traditional SMS on Android devices.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify contact.phone_number.

Phone Number Format

Note that the phone number in response is in E.164 format. All responses and webhooks coming from Amio use this format.

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/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "rbm"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

 
posthttps://api.amio.io/v1/messages
{
  "channel": {
    "id": "6456078759331238786"
  },
  "contact": {
    "phone_number": "+1 (555) 857-6309"
  },
  "content": {
    "type": "text",
    "payload": "Hello world!"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078996108088196",
  "channel": {
    "id": "6456078759331238786",
    "type": "rbm"
  },
  "contact": {
    "id": "6456078781510718339",
    "phone_number": "15558576309"
  },
  "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. phone_number
string
required

Phone number of the contact. All phone number formats are accepted.

⚠ You always need to include international call prefix.

content
object
content.type
string
required

Must be set to text.

content.payload
string
required

Text to be sent encoded in UTF-8. The maximum size of a message is 250 KB.

 
 

Run in Postman

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

Agent State

Unlike other channels, the RBM channel is completely maintained by Amio. Once you create an RBM channel, it exists only in Amio and you need to give us a request to register an agent in RBM.

The states are:

  • new - an agent doesn't exist in Google.
  • create_requested - we received your request to register the agent in Google.
  • created - the agent can be used with test phone numbers only.
  • launch_requested - we received your request to launch the agent.
  • launched - you can send RCS messages to any phone number.
Suggest Edits

List Channels

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

You couldn't be authenticated

[
  {
    "id": "6555093381403135744",
    "type": "rbm",
    "name": "Amio.io",
    "mode": "production",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    },
    "rbm": {
      "agent_name": "My Agent",
      "agent_state": "launched",
      "region": "europe"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: rbm.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent through RBM.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through RBM.

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.

rbm

object

Contains information specific to an RBM agent.

rbm.agent_name

string

Name of the agent as it is shown to end users.

rbm.agent_state

string

Agent state describes whether your agent is registered in RBM and whether it is launched.

region

string

Agent region.

Suggest Edits

Get Channel

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

You couldn't be authenticated

{
  "id": "6555093381403135744",
  "type": "rbm",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "rbm": {
    "agent_name": "My Agent",
    "agent_state": "launched",
    "region": "europe"
  }
}

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: rbm.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent through RBM.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through RBM.

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.

rbm

object

Contains information specific to an RBM agent.

rbm.agent_name

string

Name of the agent as it is shown to end users.

rbm.agent_state

string

Agent state describes whether your agent is registered in RBM and whether it is launched.

rbm.region

string

Agent region.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "rbm",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "rbm": {
    "agent_name": "ACME",
    "region": "europe"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "type": "rbm",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "rbm": {
    "agent_name": "ACME",
    "agent_state": "new",
    "region": "europe"
  }
}

Body Params

type
string
required

Channel type, rbm.

name
string

Name of the channel. If not set, it will be generated from rbm.agent_name.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

rbm
object
rbm.agent_name
string
required

Name of the agent as it is shown to end users.

rbm.region
string

Region is needed for Agent registration in RBM. Allowed regions are asia_pacific, europe and north_america.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: rbm.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent through RBM.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through RBM.

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.

rbm

object

Contains information specific to an RBM agent.

rbm.agent_name

string

Name of the agent as it is shown to end users.

rbm.agent_state

string

Agent state describes whether your agent is registered in RBM and whether it is launched.

region

string

Agent region.

Suggest Edits

Update Channel

 
patchhttps://api.amio.io/v1/channels/channel_id
{
  "type": "rbm",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "rbm": {
    "agent_name": "ACME",
    "agent_state": "create_requested",
    "region": "europe"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "type": "rbm",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks"
  },
  "rbm": {
    "agent_name": "ACME",
    "agent_state": "new",
    "region": "europe"
  }
}

Body Params

name
string

Name of the channel.

mode
string

Mode of the channel. production - Send Message requests will be accepted and sent through RBM. test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through RBM.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

rbm
object
rbm.agent_name
string

Name of the agent as it is shown to end users.

rbm.agent_state
string

Agent state describes whether your agent is registered in RBM and whether it is launched.

Allowed values are:
- create_requested when Agent State is new
- launch_requested when Agent State is created

rbm.region
string

Region is needed for Agent registration in RBM. Allowed regions are asia_pacific, europe and north_america.

Can only changed when Agent State is new.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: rbm.

name

string

Name of the channel.

mode

string

Mode of the channel.
production - Send Message requests will be accepted and sent through RBM.
test - Send Message requests will be accepted but won't be processed any further. This avoids the cost of sending the message through RBM.

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.

rbm

object

Contains information specific to an RBM agent.

rbm.agent_name

string

Name of the agent as it is shown to end users.

rbm.agent_state

string

Agent state describes whether your agent is registered in RBM and whether it is launched.

region

string

Agent region.

Suggest Edits

Delete Channel

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

You couldn't be authenticated

Path Params

channel_id
string
required

Id of the channel.

 
 

Run in Postman

Contact represents the mobile number owner. Contact is automatically created whenever you send a message to a new phone number or when you receive a message from the user.

Suggest Edits

List Contacts

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

You couldn't be authenticated

[
  {
    "id": "6456078781510718339",
    "name": "15558576309",
    "phone_number": "15558576309"
  }
]

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. Phone number by default.

phone_number

string

Phone number of the contact (E.164 format).

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/6456078759331238786/contacts/6456078781510718339
A binary file was returned

You couldn't be authenticated

{
  "id": "6456078781510718339",
  "name": "15558576309",
  "phone_number": "15558576309"
}

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. Phone number by default.

phone_number

string

Phone number of the contact (E.164 format).

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/6456078759331238786/contacts/6456078781510718339
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 RBM platform.

Suggest Edits

Message Received

 

This event is fired whenever a reply from a contact is received.

{
  "event": "message_received",
  "timestamp": "2016-10-06T13:42:48Z",
  "data": {
    "id": "6456078996108088196",
    "channel": {
      "id": "6456078759331238786",
      "type": "rbm"
    },
    "contact": {
      "id": "6456078781510718339",
      "phone_number": "15558576309"
    },
    "content": {
      "type": "text",
      "payload": "That's really nice that I can write you here. You guys rock!"
    },
    "nlp": {...}
  }
}
Parameter
Type
Description

data

object

Object representing message received. The structure matches Send Message response structure except for the nlp key which is valid only for received messages.

data.nlp

object

 

Telegram is popular, privacy-focused messenger with more than 200 million users.

 

Run in Postman

Message resource is the main entry point for sending messages. To send a message, you have to specify a Telegram contact id. You receive contact.id when a user starts a conversation with you.

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/6456078759331238786/contacts/6456078781510718339/messages
A binary file was returned

You couldn't be authenticated

[
  {
    "id": "6456078996108088196",
    "direction": "sent",
    "sent": "2018-02-06T19:15:38.860Z",
    "delivered": null,
    "read": null,
    "channel": {
      "id": "6456078759331238786",
      "type": "telegram"
    },
    "contact": {
      "id": "6456078781510718339"
    },
    "content": {
      "payload": "text",
      "type": "Hello world!"
    }
  }
]

Path Params

channel_id
string
required

Id of the channel.

contact_id
string
required

Id of the contact.

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

You couldn't be authenticated

{
  "id": "6555113982310240129",
  "channel": {
    "id": "6555093381403135744",
    "type": "telegram"
  },
  "contact": {
    "id": "6555112211957436097"
  },
  "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 4096 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": "6555093381403135744",
    "type": "telegram",
    "name": "Amio.io",
    "mode": "production",
    "webhook": {
      "id": "6456079006639985542",
      "url": "https://my-project.com/webhooks",
      "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
      "ssl_verification": true
    },
    "telegram": {
      "access_token": "123456789:ATRY9Bwa0raXG-rsIUUzPpwgtdsdhhy7PY",
      "name": "Amio.io",
      "username": "amio_io_bot"
    }
  }
]
 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: telegram.

name

string

Name of the channel.

mode

string

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

telegram

object

Represents a Telegram Bot connected to the channel.

telegram.name

string

Name of the Telegram Bot.

telegram.username

string

Username of the Telegram Bot.

telegram.access_token

string

Telegram Bot access token.

Suggest Edits

Get Channel

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

You couldn't be authenticated

{
  "id": "6555093381403135744",
  "type": "telegram",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "telegram": {
    "access_token": "123456789:ATRY9Bwa0raXG-rsIUUzPpwgtdsdhhy7PY",
    "name": "Amio.io",
    "username": "amio_io_bot"
  }
}

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: telegram.

name

string

Name of the channel.

mode

string

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

telegram

object

Represents a Telegram Bot connected to the channel.

telegram.name

string

Name of the Telegram Bot.

telegram.username

string

Username of the Telegram Bot.

telegram.access_token

string

Telegram Bot access token.

Suggest Edits

Create Channel

 
posthttps://api.amio.io/v1/channels
{
  "type": "telegram",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "url": "https://my-project.com/webhooks",
  },
  "telegram": {
    "access_token": "123456789:ATRY9Bwa0raXG-rsIUUzPpwgtdsdhhy7PY"
  }
}
A binary file was returned

You couldn't be authenticated

{
  "id": "6555093381403135744",
  "type": "telegram",
  "name": "Amio.io",
  "mode": "production",
  "webhook": {
    "id": "6456079006639985542",
    "url": "https://my-project.com/webhooks",
    "secret": "6OUlfYyRZ393ZEoSncNAZfoCN0WveK",
    "ssl_verification": true
  },
  "telegram": {
    "access_token": "123456789:ATRY9Bwa0raXG-rsIUUzPpwgtdsdhhy7PY",
    "name": "Amio.io",
    "username": "amio_io_bot"
  }
}

Body Params

type
string
required

Channel type, telegram.

name
string

Name of the channel. If not set, prefilled with the connected Telegram Bot name.

webhook
object
webhook.url
string

Webhook url where all channel events would be sent to.

telegram
object
telegram.access_token
string
required

Telegram Bot access token. It has to be unique since Telegram Bot account can be only assigned to one channel. You received this token when you created your Telegram Bot.

mode
string

Mode of the channel. Only production mode is allowed.

 

Response Body Params

Parameter
Type
Description

id

string

Id of the channel.

type

string

Channel type specifying the underlying platform: telegram.

name

string

Name of the channel.

mode

string

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

telegram

object

Represents a Telegram Bot connected to the channel.