Contacts

Contact represents the end user on given channel. Contact is automatically created whenever you receive a message from the user for the first time. However, there are also different ways how you can create the contact (i.e. for Mobile platform the user is created when you send a message to the given phone number).

Contact Merging

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

Note

See channel specific requests to see differences between contacts on each channel:

• Amio Chat - Contacts
• Facebook Messenger - Contacts
• Mobile - Contacts
• RCS Business Messages - Contacts
• Telegram - Contacts
• Viber Bot - Contacts
• Viber Business Messages - Contacts

List Contacts

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.

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

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

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

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

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

Delete Contact

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

DELETE https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact to be deleted.

Response 204

Channel-specific contacts

Select a channel to see its specifics.

Amio Chat

Amio Chat: Overview

Contact represents the Amio chat user. Contact is automatically created whenever you receive a message from the user for the first time.

Amio Chat: List Contacts

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.

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

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

Amio Chat: Get 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.

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

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

Amio Chat: Delete Contact

DELETE https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact to be deleted.

Response 204

Email (Daktela)

Email (Daktela): Overview

Contact represents an email address. Contact is automatically created when a message is received from an email address for the first time.

Email (Daktela): List Contacts

Response Body Params

Parameter	Type	Description
id	string	Id of the contact. Id is unique across channels and is generated by Amio.
name	string	Contact’s email address.

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
max	query	integer		Maximum number of contacts to retrieve.
offset	query	integer		Offset of the retrieved contact list.

Response 200

[
  {
    "id": "6619965168536114630",
    "name": "john@customer.com"
  }
]

Email (Daktela): Get 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	Contact’s email address.

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

{
  "id": "6619965168536114630",
  "name": "john@customer.com"
}

Email (Daktela): Delete Contact

DELETE https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 204

Facebook Messenger

Facebook Messenger: Overview

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

Facebook Messenger: List Contacts

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.

Caution

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

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

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

Facebook Messenger: Get 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.

Caution

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.

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

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

Facebook Messenger: Delete Contact

Same as Amio Chat: Delete Contact.

Mobile (SMS)

Mobile (SMS): Overview

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.

Mobile (SMS): List Contacts

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

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

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

Mobile (SMS): Get 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).

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

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

Mobile (SMS): Delete Contact

Same as Amio Chat: Delete Contact.

RCS Business Messages

RCS Business Messages: Overview

Same as Mobile (SMS): Overview.

RCS Business Messages: List Contacts

Same as Mobile (SMS): List Contacts.

RCS Business Messages: Get Contact

Same as Mobile (SMS): Get Contact.

RCS Business Messages: Delete Contact

Same as Amio Chat: Delete Contact.

Telegram

Telegram: Overview

Contact represents the Telegram user. Contact is automatically created whenever you receive a message from the user for the first time.

Missing Contact details

Right now, Amio API doesn’t give any details about Telegram contacts, such as name, language, etc. This feature will be implemented soon.

Telegram: List Contacts

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.

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
max	query	integer		Maximum number of results to be returned. Cannot be more than 100.
offset	query	integer		Skip first N results.

Response 200

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

Telegram: Get 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.

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

{
  "id": "6555112211957436097",
  "name": "6555112211957436097"
}

Telegram: Delete Contact

Same as Email (Daktela): Delete Contact.

Viber Bot

Viber Bot: Overview

Contact represents the Viber user. Contact is automatically created whenever you receive a message from the user for the first time.

Viber Bot: List Contacts

Response Body Params

Parameter	Type	Description
id	string	Id of the contact. Id is unique across channels and is generated by Amio.
name	string	Name of the contact.
locale	string	User’s locale in standard format.
photo_url	string	Url to profile picture of the user.

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

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

Viber Bot: Get Contact

Response Body Params

Parameter	Type	Description
id	string	Id of the contact. Id is unique across channels and is generated by Amio.
name	string	Name of the contact.
locale	string	User’s locale in standard format.
photo_url	string	Url to profile picture of the user.

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

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

Viber Bot: Delete Contact

Same as Amio Chat: Delete Contact.

Viber Business Messages

Viber Business Messages: Overview

Contact represents the Viber user. Contact is automatically created whenever you send a message to a new phone number.

Viber Business Messages: List Contacts

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. In case of Viber Business Messages, name is the same as phone number.
phone_number	string	User’s phone number (E.164 format)

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

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

Viber Business Messages: Get 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. In case of Viber Business Messages, name is the same as phone number.
phone_number	string	User’s phone number (E.164 format)

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

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

Viber Business Messages: Delete Contact

Same as Amio Chat: Delete Contact.

WhatsApp

WhatsApp: Overview

Contact represents the WhatsApp user. Contact is automatically created whenever you send a message to a new phone number.

WhatsApp: List Contacts

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.
platform_id	string	User’s WhatsApp Id.
phone_number	string	Phone number is present only if you were sending notifications to a contact using phone number (a template message)

GET https://api.amio.io/v1/channels/{channel_id}/contacts

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.

Response 200

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

WhatsApp: Get 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	Phone number of the contact.
platform_id	string	User’s WhatsApp Id.
phone_number	string	Phone number is present only if you were sending notifications to a contact using phone number (a template message). If message_received is your first contact with the customers, it will contain only data.contact.id.

GET https://api.amio.io/v1/channels/{channel_id}/contacts/{contact_id}

Parameters

Name	In	Type	Required	Description
channel_id	path	string	yes	Id of the channel.
contact_id	path	string	yes	Id of the contact.

Response 200

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

WhatsApp: Delete Contact

Same as Amio Chat: Delete Contact.