Groups API

MessageBird provides an API to manage contact groups.

Groups are identified by a unique random ID. Using this ID you can create, view, update or delete groups.

URI

https://rest.messagebird.com/groups

Available HTTP Methods

POST /groups
GET /groups
GET /groups/{groupId}
GET /groups/{groupId}/contacts
PATCH /groups/{groupId}
PUT /groups/{groupId}/contacts
DELETE /groups/{groupId}
DELETE /groups/{groupId}/contacts/{contactId}

The group object

This object represents a contact group at MessageBird.com

Attributes

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
hrefstringThe URL of the created object.
namestringThe name of the group.
contactshashThe hash with contacts in group. Further explanation in the table below.
createdDatetimedatetimeThe date and time of the creation of the group in RFC3339 format (Y-m-dTH:i:sP).
updatedDatetimedatetimeThe date and time of the last update of the group in RFC3339 format (Y-m-dTH:i:sP).

Object example

{
"id": "61afc0531573b08ddbe36e1c85602827",
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827",
"name": "Home",
"contacts": {
"totalCount": 0,
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827/contacts"
},
"createdDatetime": "2016-04-29T09:42:26+00:00",
"updatedDatetime": "2016-04-29T09:42:26+00:00"
}

The contacts hash

AttributeTypeDescription
totalCountintegerThe total count of contacts in group.
hrefstringURL which can be used to retrieve list of contacts in group.

Create a group

Creates a new group object. MessageBird returns the created group object with each request.

Required parameters

ParameterTypeDescription
namestringThe name of the group. Required

Definition

POST https://rest.messagebird.com/groups

Example request

$ curl -X POST https://rest.messagebird.com/groups \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \ -d "name=Home"
Notification icon

Do note that values are not automatically urlencoded with the above example. Use --data-urlencode if you want to urlencode the values.

Returns

Returns a group object if the request was successful. If the request failed, an error object will be returned.

Example response

{
"id": "61afc0531573b08ddbe36e1c85602827",
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827",
"name": "Home",
"contacts": {
"totalCount": 0,
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827/contacts"
},
"createdDatetime": "2016-04-29T09:42:26+00:00",
"updatedDatetime": "2016-04-29T09:42:26+00:00"
}

View a group

Retrieves the information of an existing group. You only need to supply the unique group ID that was returned upon creation or receiving.

Required parameters

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

Definition

GET https://rest.messagebird.com/groups/{groupId}

Example request

$ curl -X GET https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827 \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Returns

Returns a group object if the request was successful. If the request failed, an error object will be returned.

Example response

{
"id": "61afc0531573b08ddbe36e1c85602827",
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827",
"name": "Home",
"contacts": {
"totalCount": 0,
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827/contacts"
},
"createdDatetime": "2016-04-29T09:42:26+00:00",
"updatedDatetime": "2016-04-29T09:42:26+00:00"
}

Update a group

Updates an existing group. 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

PATCH https://rest.messagebird.com/groups/{groupId}

Example request

$ curl -X PATCH https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827 \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \ -d "name=Work"
Notification icon

Do note that values are not automatically urlencoded with the above example. Use --data-urlencode if you want to urlencode the values.

Returns

Returns an HTTP header of 200 OK and the group object if the request was successful. If the request failed, an error object will be returned.

Example response

{
"id": "61afc0531573b08ddbe36e1c85602827",
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827",
"name": "Work",
"contacts": {
"totalCount": 0,
"href": "https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827/contacts"
},
"createdDatetime": "2016-04-29T09:42:26+00:00",
"updatedDatetime": "2016-04-29T09:42:26+00:00"
}

Add contact to group

Adds contact to group. You need to supply the IDs of the group and contact.

Required parameters

ParameterTypeDescription
groupIdstringThe ID of the group. Required
idsarrayThe ID of the contacts to add. Max. 50. Required

Definition

PUT https://rest.messagebird.com/groups/{groupId}/contacts

Example request

$ curl -X PUT https://rest.messagebird.com/groups/61afc0531573b08ddbe36e1c85602827/contacts \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \ -d "ids[]=38afc3b2156e00498764d21c57738631" -d "ids[]=9a0ca1f2156e0028f511af2c13800145"
Notification icon

Do note that values are not automatically urlencoded with the above example. Use --data-urlencode if you want to urlencode the values.

Returns

Returns an HTTP header of 204 accepted if the request was successful. If the request failed, an error object will be returned.

Example response

[empty]

Remove contact from group

Removes a contact from group. You need to supply the IDs of the group and contact. Does not delete the contact.

Required parameters

ParameterTypeDescription
groupIdstringThe ID of the group. Required
contactIdarrayThe ID of the contact to remove. Required

Definition

DELETE https://rest.messagebird.com/groups/{groupId}/contacts/{contactId}

Example request

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

Returns

Returns an HTTP header of 204 accepted if the request was successful. If the request failed, an error object will be returned.

Example response

[empty]

Delete a group

Deletes an existing group. 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://rest.messagebird.com/groups/{groupId}

Example request

$ curl -X DELETE https://rest.messagebird.com/groups/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]
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings