API Reference

OverviewSMSVoice CallingVoice MessagingConversations APIIntegrations APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroups

Contacts API (V2) Early Access

The Contacts API (V2) is currently in Early Access and during this period is only used by customers using Programmable Conversations API.

MessageBird’s Contacts API (V2) allows you to create and manage a single omni-channel profile for any customer you message on any of MessageBird’s supported platforms. This means that regardless of which platform a customer is messaging you on, you will always be able to identify who they are. Contacts API V2 is available for all customers using Programmable Conversations to message their customers over Facebook Messenger, LINE, Telegram, WeChat, SMS, and WhatsApp.

API Endpoint

https://contacts.messagebird.com/v2

Endpoints Summary

// Contacts
GET /contacts
POST /contacts
GET /contacts/{id}
PATCH /contacts/{id}
DELETE /contacts/{id}
// Identifiers
POST /contacts/{id}/identifiers
DELETE /contacts/{id}/identifiers/{id}
// Imports
POST /import/contacts
GET /import/contacts/{import_id}/status

Authorization

With each API call you'll need to set an access key to authenticate yourself. API keys can be created or retrieved through the MessageBird Dashboard.

To provide the access key, set the Authorization header in the form of AccessKey {accessKey}.

Formats and Headers

All API responses are in JSON. You're required to send the Accept header with the value application/json with each request.

POST and PUT requests to the API must contain a JSON-formatted payload in the request body.

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).

In the case of an error, the body of the response includes a JSON-formatted response that tells you exactly what is wrong.

Error Object Example

{
"errors": [
{
"code": 2,
"description": "Request not allowed (incorrect access_key)",
"parameter": "access_key"
}
]
}

Attributes

AttributeTypeDescription
errors[].codeintegerAn integer that represents the error type.
errors[].descriptionstringA human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameterstringThe parameter in your request related to the error if the error is parameter specific.

The Contact object

A Contact represents an end-user or customer that you have been in touch with on a messaging platform. A single contact might be present across multiple platforms, e.g. you might have a customer "Jane Doe" and she can be reached on SMS, WhatsApp, and Telegram because she has reached out to your business across all of these platforms. Jane can exist as a single contact in the Contacts API to make repeated communication seamless, regardless of what platform you're talking over.

Attributes

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the contact.
displayNamestringA display name (e.g. "{firstName} {lastName}", a username, or phone number) for the contact, typically used when displaying a contact in UI.
firstNamestringOptional. The first name of the contact.
lastNamestringOptional. The last name of the contact.
languagesArrayOptional. An array of language identifiers. Will be populated with ISO 639-1 codes for the language of this contact if the contact has messaged on a platform that provides locale data.
countrystringOptional. An identifier the country this contact resides in. Will be populated with an ISO 3166-1 code if the contact has messaged on a platform that provides country data.
avatarstringOptional. A URL linking to an avatar for this contact.
genderstringOptional. A gender identifier for the customer. Free text format.
statusstringThe status of this contact, one of: active, merged.
profilesArray of ProfileOptional. An array of the profiles that link this Contact to a specific channel.
attributesJSONOptional. Custom key-value attributes that can be assigned to the contact. Any valid JSON object is accepted, but the maximum size of the object is 10kB.
hrefstringThe URL for this contact resource.
createdAtdateRFC3339 formatted timestamp of the creation time of the contact.
updatedAtdateRFC3339 formatted timestamp of the time of the last update made to the contact.

Example Contact

{
"id": "f4a4af42f9894b56b6f7b3418443b2e1",
"href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"identifiers": [
{
"id": "d4095cbec4be475c862f329b109e961e",
"type": "emailaddress",
"value": "jane.tester@messagebird.com"
},
{
"id": "5abffd64e6aa445fa9947449e44c49f0",
"type": "phonenumber",
"value": "3112345678"
}
],
"languages": [
"en",
"nl"
],
"timezone": "UTC+1",
"country": "NL",
"avatar": "https://example.com/avatar.png",
"gender": "f",
"profiles": [
{
"id": "de93f56a2d7442d3b1e9048637c7382e",
"channelId": "d759a993508e42e49fa74afc0687cc4b",
"identifier": "3112345678"
}
],
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
},
"status": "active",
"createdAt": "2019-05-08T12:23:19Z",
"updatedAt": "2019-05-08T12:23:19Z"
}

The Identifier object

An Identifier is a value used by other platforms to Identify a contact. This can be a generic identifier such as a phone number or email address that are used with multiple platforms, as well as some platform specific identifiers such as your Facebook ID.

Attributes

AttributeTypeDescription
idstringA unique random ID used to identify this identifier on the MessageBird platform.
typestringThe type of identifier.
valuestringThe identifier of the user on the provided channel.

Types

Here is a list of possible identifier types. This list will expand as we add new channels.

TypeDescription
phonenumberA valid MSISDN used by channels like WhatsApp and SMS.
emailaddressEmail Address used by channels identifying with email.
facebookFacebook user ID, Can only be used with the Facebook channel.
wechatWeChat user ID. Can only be used with the WeChat channel.
lineLine user ID. Can only be used with the Line channel.
telegramTelegram user ID. Can only be used with the Telegram channel.
instagramInstagram user ID. Can only be used with the Instagram channel.
twitterTwitter user ID. Can only be used with the Twitter channel.

The Profile object

The Profile object is a link between your contact on MessageBird and one of your configured messaging channels, e.g. a Facebook page, Telegram bot, or WhatsApp Business Account. Identifiers depend on the platform, for example, a WhatsApp channel identifier is an MSISDN registered to a user's account on WhatsApp, a Facebook identifier is a page-scoped ID value provided by Facebook.

There is no limit to the number of profiles a contact can have. Some platforms, such as Facebook Messenger, have a different user identifier per page. This means your contact can have a profile for each configured channel even if some of those channels belong to the same platform.

Attributes

AttributeTypeDescription
idstringA unique random ID used to identify this profile on the MessageBird platform.
channelIdstringThe id of the MessageBird channel for this profile.
identifierstringThe platform-specific identifier of the user on the provided channel.

List all Contacts

Retrieves all contacts for this account. By default, contacts are sorted by the createdAt field so that all new contacts appear first.

Parameters

No parameters are required; however, filters and pagination can be provided through the following optional query parameters:

ParameterTypeDescriptionExample
idsstringComma separated list of contact ids to filter.ids=idA,idB,idC
channelIdstringOnly return contacts that have a profile associated with this channel.channelId=2ccb501a4b0e440a8779103478292f84
identifierExactstringOnly return contacts with this Identifier associated to the contact.identifierExact=jane.tester@messagebird.com
statusstringContact status. active or merged. Default: active.status=active
limitintegerThe number of maximum objects to return on each request. Default: 20limit=10
offsetintegerThe number of objects to skip from the first. Default: 0offset=120

Definition

GET https://contacts.messagebird.com/v2/contacts

Example request

curl "https://contacts.messagebird.com/v2/contacts?channelId=d759a993508e42e49fa74afc0687cc4b&status=active&offset=40&limit=10" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
-H 'Content-Type: application/json; charset=utf-8'

Example response

{
"totalCount": 43,
"count": 3,
"offset": 10,
"limit": 10,
"items": [
{
"id": "f4a4af42f9894b56b6f7b3418443b2e1",
"href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"identifiers": [
{
"id": "d4095cbec4be475c862f329b109e961e",
"type": "emailaddress",
"value": "jane.tester@messagebird.com"
},
{
"id": "5abffd64e6aa445fa9947449e44c49f0",
"type": "phonenumber",
"value": "3112345678"
}
],
"languages": [
"en",
"nl"
],
"timezone": "UTC+1",
"country": "NL",
"avatar": "https://example.com/avatar.png",
"gender": "f",
"profiles": [
{
"id": "de93f56a2d7442d3b1e9048637c7382e",
"channelId": "d759a993508e42e49fa74afc0687cc4b",
"identifier": "3112345678"
}
],
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
},
"status": "active",
"createdAt": "2019-05-08T12:23:19Z",
"updatedAt": "2019-05-08T12:23:19Z"
},
{
"...": "..."
},
{
"...": "..."
}
]
}

Create a Contact

Create a new contact with the provided data and profiles.

Definition

POST https://contacts.messagebird.com/v2/contacts

Example request

curl -X POST "https://contacts.messagebird.com/v2/contacts" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"avatar": "https://example.com/avatar.png",
"languages": [
"en",
"nl"
],
"country": "NL",
"timezone": "UTC+1",
"gender": "f",
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
}
}'

Example response

{
"id": "f4a4af42f9894b56b6f7b3418443b2e1",
"href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"identifiers": [
{
"id": "d4095cbec4be475c862f329b109e961e",
"type": "emailaddress",
"value": "jane.tester@messagebird.com"
},
{
"id": "5abffd64e6aa445fa9947449e44c49f0",
"type": "phonenumber",
"value": "3112345678"
}
],
"languages": [
"en",
"nl"
],
"timezone": "UTC+1",
"country": "NL",
"avatar": "https://example.com/avatar.png",
"gender": "f",
"profiles": [],
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
},
"status": "active",
"createdAt": "2019-05-08T12:23:19Z",
"updatedAt": "2019-05-08T12:23:19Z"
}

View a Contact

Find an existing contact by id.

Definition

GET https://contacts.messagebird.com/v2/contacts/{id}

Example request

curl "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
-H 'Content-Type: application/json; charset=utf-8'

Example response

{
"id": "f4a4af42f9894b56b6f7b3418443b2e1",
"href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"identifiers": [
{
"id": "d4095cbec4be475c862f329b109e961e",
"type": "emailaddress",
"value": "jane.tester@messagebird.com"
},
{
"id": "5abffd64e6aa445fa9947449e44c49f0",
"type": "phonenumber",
"value": "3112345678"
}
],
"languages": [
"en",
"nl"
],
"timezone": "UTC+1",
"country": "NL",
"avatar": "https://example.com/avatar.png",
"gender": "f",
"profiles": [
{
"id": "de93f56a2d7442d3b1e9048637c7382e",
"channelId": "d759a993508e42e49fa74afc0687cc4b",
"identifier": "3112345678"
}
],
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
},
"status": "active",
"createdAt": "2019-05-08T12:23:19Z",
"updatedAt": "2019-05-08T12:23:19Z"
}

Update a Contact

Update properties of an existing contact by id. As this is a PATCH request, only fields that require changes need to be provided in the request.

The languages array field will be updated by replacing the entire array with what is provided in the request.

The attributes field will be updated as an RFC7386 merge patch. Existing attributes will be merged with new attributes provided in the patch request. If a key exists in the existing attributes and the patched attributes, it will be overwritten with the value from the patched attributes. Deleting an attribute is possible by setting it's value to null in the patch request.

Definition

PATCH https://contacts.messagebird.com/v2/contacts/{id}

Example request

curl -X PATCH "https://contacts.messagebird.com/v2/contacts/0b0f86191edb46cbb47c108f2c11d5a6" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"displayName": "Jane from MessageBird",
"languages": ["en", "fr"],
"attributes": {
"company": "MessageBird",
"team": "Product Engineering"
}
}'

Example response

{
"id": "f4a4af42f9894b56b6f7b3418443b2e1",
"href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"identifiers": [
{
"id": "d4095cbec4be475c862f329b109e961e",
"type": "emailaddress",
"value": "jane.tester@messagebird.com"
},
{
"id": "5abffd64e6aa445fa9947449e44c49f0",
"type": "phonenumber",
"value": "3112345678"
}
],
"languages": [
"en",
"nl"
],
"timezone": "UTC+1",
"country": "NL",
"avatar": "https://example.com/avatar.png",
"gender": "f",
"profiles": [
{
"id": "de93f56a2d7442d3b1e9048637c7382e",
"channelId": "d759a993508e42e49fa74afc0687cc4b",
"identifier": "3112345678"
}
],
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
},
"status": "active",
"createdAt": "2019-05-08T12:23:19Z",
"updatedAt": "2019-05-08T12:23:19Z"
}

Update or Create Contact.

This method looks for an existing contact with passed identifiers and updates it with new ones from the request. If contact with such identifiers does not exist, it will create one. It returns updated or created contact ID and a flag that indicates if a contact was created. If updateContact argument set to false, contact fields will not be updated if the contact already exists. Pass false if you are unsure.

Use it if you don't know if a contact exists, otherwise use PATCH contact.

Attributes

AttributeTypeDescription
updateContactbooleanWeather to update contact if exists or not
contact.idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the contact.
contact.displayNamestringA display name (e.g. "{firstName} {lastName}", a username, or phone number) for the contact, typically used when displaying a contact in UI.
contact.firstNamestringOptional. The first name of the contact.
contact.lastNamestringOptional. The last name of the contact.
contact.emailstringDEPRECATED (Use Identifiers instead). The primary registered email address for this contact.
contact.phonestringDEPRECATED (Use Identifiers instead). The primary registered phone number for this contact.
contact.languagesArrayOptional. An array of language identifiers. Will be populated with ISO 639-1 codes for the language of this contact if the contact has messaged on a platform that provides locale data.
contact.countrystringOptional. An identifier the country this contact resides in. Will be populated with an ISO 3166-1 code if the contact has messaged on a platform that provides country data.
contact.avatarstringOptional. A URL linking to an avatar for this contact.
contact.genderstringOptional. A gender identifier for the customer. Free text format.
contact.statusstringThe status of this contact, one of: active, merged.
contact.profilesArray of ProfileOptional. An array of the profiles that link this Contact to a specific channel.
contact.identifiersArray of IdentifierOptional. An array of the identifiers that link this Contact.
contact.attributesJSONOptional. Custom key-value attributes that can be assigned to the contact. Any valid JSON object is accepted, but the maximum size of the object is 10kB.
contact.hrefstringThe URL for this contact resource.
contact.createdAtdateRFC3339 formatted timestamp of the creation time of the contact.
contact.updatedAtdateRFC3339 formatted timestamp of the time of the last update made to the contact.

Definition

POST https://contacts.messagebird.com/v2/ops/contacts/upsert

Example request

curl -X POST "https://contacts.messagebird.com/v2/ops/contacts/upsert" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"updateContact": true,
"contact": {
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"avatar": "https://example.com/avatar.png",
"languages": [
"en",
"nl"
],
"country": "NL",
"timezone": "UTC+1",
"gender": "f",
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
}
}
}'

Example response

{
"contactId": "f4a4af42f9894b56b6f7b3418443b2e1",
"created": true
}

Delete a Contact

Deletes a contact and its profiles. You only need to supply the unique id that was returned upon creation.

Required parameters

ParameterTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Definition

DELETE https://contacts.messagebird.com/v2/contacts/{id}

Example request

curl -X DELETE https://rest.messagebird.com/v2/contacts/61afc0531573b08ddbe36e1c85602827 \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Returns

Returns an HTTP header of 204 No Content and an empty response if the request was successful. If the request failed, an error object will be returned.

Example response

[empty]

Merge contacts

Merge contact into another contact. It can be used to combine data from two different contacts, which should represent the same user. The one that's passed in the URL will be the active one.

Note that if merged contact had active conversations, they will be merged as well.

Attributes

AttributeTypeDescription
originstringA unique random ID of the original contact. Required
destinationstringA unique random ID of the destination contact. Required

Definition

POST https://contacts.messagebird.com/v2/ops/contacts/merge

Example request

curl -X POST "https://contacts.messagebird.com/v2/ops/contacts/merge" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"origin": "5ff77bdc2f004451986be7e03894d52b",
"destination": "f4a4af42f9894b56b6f7b3418443b2e1"

Example response

{
"id": "f4a4af42f9894b56b6f7b3418443b2e1",
"href": "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1",
"displayName": "Jane Tester",
"firstName": "Jane",
"lastName": "Tester",
"identifiers": [
{
"id": "d4095cbec4be475c862f329b109e961e",
"type": "emailaddress",
"value": "jane.tester@messagebird.com"
},
{
"id": "5abffd64e6aa445fa9947449e44c49f0",
"type": "phonenumber",
"value": "3112345678"
}
],
"languages": [
"en",
"nl"
],
"timezone": "UTC+1",
"country": "NL",
"avatar": "https://example.com/avatar.png",
"gender": "f",
"profiles": [
{
"id": "de93f56a2d7442d3b1e9048637c7382e",
"channelId": "d759a993508e42e49fa74afc0687cc4b",
"identifier": "3112345678"
}
],
"attributes": {
"membership": "platinum",
"status": "vip",
"customerNumber": "1234"
},
"status": "active",
"createdAt": "2019-05-08T12:23:19Z",
"updatedAt": "2019-05-08T12:23:19Z"
}

Add an Identifier to an existing Contact

Link a identifier of a provided type to an existing Contact. Use this endpoint to add any known identifiers to a contact (such as email, phone, etc.).

Definition

POST https://contacts.messagebird.com/v2/contacts/{id}/identifiers

Example request

curl -X POST "https://contacts.messagebird.com/v2/contacts/f4a4af42f9894b56b6f7b3418443b2e1/identifiers" \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"type": "emailaddress",
"value": "mark@gmail.com"
}'

Example response

{
"id": "35964e692de14a8ca79ef0facb8d6c28",
"type": "emailaddress",
"value": "mark@gmail.com",
"createdAt": "2019-05-08T12:23:19Z"
}

Import Contacts

This endpoint allows you to upload up to 100k of contacts in a csv file format. The required structure of a file is shown below. When you’re uploading a csv file, keep in mind that the headers must be set according to the headers fields below.

File header fields

HeaderTypeDescription
phonestringOptional. The primary registered phone number for this contact.
emailstringOptional. The primary registered email address for this contact.
firstNamestringOptional. The first name of the contact.
lastNamestringOptional. The last name of the contact.
displayNamestringA display name (e.g. "{firstName} {lastName}", a username, or phone number) for the contact, typically used when displaying a contact in UI.
custom:keystringAny custom attributes you want to include in the contact, where key is a unique key in the contacts Attribute object. Eg: custom:account_id

Definition

POST https://contacts.messagebird.com/v2/import/contacts

Example request

curl -X POST https://contacts.messagebird.com/v2/import/contacts \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy" \
-H 'Content-Type: text/csv' \
-H 'Content-Disposition: form-data; name="contacts"; filename="contacts.csv"' \
-d '@test.csv'

Sample CSV File

phone,email,firstName,lastName,displayName,custom:membership,custom:status,custom:customerNumber
+31612345678,johandoe@messagebird.com,John,Doe,John Doe,silver,,1111
+3112345678,,Jane,Tester,Jane Tester,platinum,vip,1234

Response

When a file is uploaded, its id and tracking URL are created accordingly. The status of the importing contacts should be tracked with the url output.

Example response

{
"id":"123123123123"
"href":"https://contacts.messagebird.com/v2/import/contacts/123123123123/status"
}

Track a Imported File

To track the imported file, provide the unique random id that is returned when the file was imported.

Required parameters

ParameterTypeDescription
idstringA unique random id created on the MessageBird platform that is returned when a file is imported. Required

Definition

GET https://contacts.messagebird.com/v2/import/contacts/{import_id}/status

Example request

curl "https://contacts.messagebird.com/v2/import/contacts/{import_id}/status" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0Qy"

Response

If the request is successful, it will return 200—this means the id exists; the response body will be as below. If the request fails, it means that the id could not be found.

AttributesTypeDescription
statusstringStatus of the tracking. It can be completed, failed, queued or in progress
messagestringDescribing the status of importing the file

Example response

{
status: “in progress”,
message: “importing”
}
Next upApi

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings