A group is a set of phone numbers (or MSISDNs) that can be used as a target when sending an SMS. An phone number (MSISDN) can only occur once in a group and any attempts to add a duplicate are ignored but not rejected.
With the list operation you can list all groups that you have created. This operation supports pagination.
Groups are returned in reverse chronological order.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
A successful response, or an Error.
Bad request
{- "page": 50,
- "page_size": 50,
- "count": 1,
- "groups": [
- {
- "name": "My First Group",
- "members": [
- "+14155553421",
- "+13435552671",
- "+14325552677"
], - "auto_update": {
- "to": "+453234457784",
- "add": {
- "first_word": "join",
- "second_word": "add"
}, - "remove": {
- "first_word": "leave",
- "second_word": "remove"
}
}
}
]
}
This endpoint allows you to create a group of recipients. A new group must be created with a group name. This is represented by the name
field which can be up to 20 charecters. In addition, there are a number of optional fields:
members
field enables groups to be created with an initial list of contactsauto_update
allows customers to auto subscribe to a new group. This contains three fields. The to
field contains the group creator's number. (This number must be provisioned by contacting your account manager.) The add
and remove
fields are objects containing the keywords that customers need to text to join or leave a group.service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
name | string [ 1 .. 20 ] characters Name of group if set. |
object (ApiGroupAutoUpdate) | |
child_groups | Array of strings [ 0 .. 10 ] items unique Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs. |
members | Array of strings <E.164> [ 0 .. 10000 ] items unique Initial list of phone numbers in E.164 format MSISDNs for the group. |
Created, or an Error.
id | string The ID used to reference this group. |
name | string [ 1 .. 20 ] characters Name of group if set. |
size | integer <int32> The number of members currently in the group. |
created_at | string <date-time> Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
modified_at | string <date-time> Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
object (ApiGroupAutoUpdate) | |
child_groups | Array of strings [ 0 .. 10 ] items unique Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs. |
Bad request
Forbidden
{- "members": [
- "member_MSISDNs",
- "as_strings_in_array",
- "16051234567"
], - "name": "YOUR_group_name"
}
{- "id": "01FC66621XXXXX119Z8PMV1QPU",
- "name": "My new customers",
- "size": 2,
- "created_at": "2019-08-24T14:15:22Z",
- "modified_at": "2019-08-24T14:15:22Z",
- "auto_update": {
- "to": 15551231234,
- "add": "join",
- "remove": "leave"
}
}
This operation retrieves a specific group with the provided group ID.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
group_id required | string ID of a group that you are interested in getting. |
A successful response, or an Error.
id | string The ID used to reference this group. |
name | string [ 1 .. 20 ] characters Name of group if set. |
size | integer <int32> The number of members currently in the group. |
created_at | string <date-time> Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
modified_at | string <date-time> Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
object (ApiGroupAutoUpdate) | |
child_groups | Array of strings [ 0 .. 10 ] items unique Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs. |
{- "id": "01FC66621VHDBN119Z8PMV1QPQ",
- "name": "My new customers",
- "size": 2,
- "created_at": "2019-08-24T14:15:22Z",
- "modified_at": "2019-08-24T14:15:22Z",
- "auto_update": {
- "to": "+15551231234",
- "add": {
- "first_word": "Sinch",
- "second_word": "JOIN"
}, - "remove": {
- "first_word": "LEAVE"
}
}, - "child_groups": [
- "string"
]
}
With the update group operation, you can add and remove members in an existing group as well as rename the group.
This method encompasses a few ways to update a group:
add
and remove
arrays containing phone numbers, you control the group movements. Any list of valid numbers in E.164 format can be added.auto_update
object, your customer can add or remove themselves from groups. add_from_group
and remove_from_group
.service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
group_id required | string ID of a group that you are interested in getting. |
add | Array of strings <E.164> [ 0 .. 10000 ] items Add a list of phone numbers (MSISDNs) to this group. The phone numbers are a strings within an array and must be in E.164 format. |
remove | Array of strings <E.164> [ 0 .. 10000 ] items Remove a list of phone numbers (MSISDNs) to this group.The phone numbers are a strings within an array and must be in E.164 format. |
name | string [ 1 .. 20 ] characters The name of the group. Omitting |
add_from_group | string (addFromGroupId) Copy the members from the another group into this group. Constraints: Must be valid group ID |
remove_from_group | string (removeFromGroupId) Remove the members in a specified group from this group. Constraints: Must be valid group ID |
object (ApiGroupAutoUpdate) |
A successful response, or an Error.
id | string The ID used to reference this group. |
name | string [ 1 .. 20 ] characters Name of group if set. |
size | integer <int32> The number of members currently in the group. |
created_at | string <date-time> Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
modified_at | string <date-time> Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
object (ApiGroupAutoUpdate) | |
child_groups | Array of strings [ 0 .. 10 ] items unique Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs. |
Bad request
Forbidden
{- "add": [
- "+14058961234",
- "+447911123456",
- "+55987654321"
], - "remove": [
- "+4612345678",
- "+15551235555"
]
}
{- "id": "01FC66621VHDBN119Z8PMV1QPQ",
- "name": "My new customers",
- "size": 2,
- "created_at": "2019-08-24T14:15:22Z",
- "modified_at": "2019-08-24T14:15:22Z",
- "auto_update": {
- "to": "+15551231234",
- "add": {
- "first_word": "Sinch",
- "second_word": "JOIN"
}, - "remove": {
- "first_word": "LEAVE"
}
}, - "child_groups": [
- "string"
]
}
The replace operation will replace all parameters, including members, of an existing group with new values.
Replacing a group targeted by a batch message scheduled in the future is allowed and changes will be reflected when the batch is sent.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
group_id required | string ID of a group that you are interested in getting. |
name | string [ 1 .. 20 ] characters Name of group if set. |
object (ApiGroupAutoUpdate) | |
child_groups | Array of strings [ 0 .. 10 ] items unique Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs. |
members | Array of strings <E.164> [ 0 .. 10000 ] items unique Initial list of phone numbers in E.164 format MSISDNs for the group. |
A successful response, or an Error.
id | string The ID used to reference this group. |
name | string [ 1 .. 20 ] characters Name of group if set. |
size | integer <int32> The number of members currently in the group. |
created_at | string <date-time> Timestamp for group creation. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
modified_at | string <date-time> Timestamp for when the group was last updated. Format: YYYY-MM-DDThh:mm:ss.SSSZ |
object (ApiGroupAutoUpdate) | |
child_groups | Array of strings [ 0 .. 10 ] items unique Phone numbers MSIDNs of child group will be included in this group. If present then this group will be auto populated. Constraints: Elements must be group IDs. |
Bad request
Forbidden
{- "members": [
- "123456789",
- "987654321"
], - "name": "New Name of the Group"
}
{- "id": "01FC66621VHDBN119Z8PMV1QPQ",
- "name": "My new customers",
- "size": 2,
- "created_at": "2019-08-24T14:15:22Z",
- "modified_at": "2019-08-24T14:15:22Z",
- "auto_update": {
- "to": "+15551231234",
- "add": {
- "first_word": "Sinch",
- "second_word": "JOIN"
}, - "remove": {
- "first_word": "LEAVE"
}
}, - "child_groups": [
- "string"
]
}
This operation deletes the group with the provided group ID.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
group_id required | string ID of a group that you are interested in getting. |
A successful response , or an Error.
This operation retrieves the members of the group with the provided group ID.
service_plan_id required | string Your service plan ID. You can find this on your Dashboard. Example: jd63jf88477ll123ab4567cd89012ef3 |
group_id required | string ID of a group that you are interested in getting. |
A successful response, or an Error.
A phone number in E.164 format.
Not found. The group ID is unknown to the system.
[- "+453234457784"
]