Groups API
Messagebird’s Groups API allows you to manage contact groups that are identified by a unique random ID. Use this ID to create, view, update or delete groups.
The Groups API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization framework. Request and response payloads are formatted as JSON—although we provide a GET alternative for requests—using UTF-8 encoding and URL encoded values.
The Group object
This object represents a contact group at MessageBird.com
Attributes
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. |
| href | string | The URL of the created object. |
| name | string | The name of the group. |
| contacts | hash | The hash with contacts in group. Further explanation in the table below. |
| createdDatetime | datetime | The date and time of the creation of the group in RFC3339 format (Y-m-d\TH:i:sP). |
| updatedDatetime | datetime | The date and time of the last update of the group in RFC3339 format (Y-m-d\TH: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
| Attribute | Type | Description |
|---|---|---|
| totalCount | integer | The total count of contacts in group. |
| href | string | URL 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
| Parameter | Type | Description |
|---|---|---|
| name | string | The 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"
In this example, values are not automatically URL encoded. Use --data-urlencode if you want to URL encode 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
| Parameter | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required |
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
| Parameter | Type | Description |
|---|---|---|
| id | string | A 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"
In this example, values are not automatically URL encoded. Use --data-urlencode if you want to URL encode 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
| Parameter | Type | Description |
|---|---|---|
| groupId | string | The ID of the group. Required |
| ids | array | The 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"
In this example, values are not automatically URL encoded. Use --data-urlencode if you want to URL encode 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.
Returns
Returns an HTTP header of 204 accepted if the request was successful. If the request failed, an error object will be returned.
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.
