Groups
Groups are where communities live in CityPay — they are a collection of contacts you're talking to all at once. On this page, we'll dive into the different group endpoints you can use to manage groups programmatically. We'll look at how to query, create, update, and delete groups.
The group model contains all the information about your groups, including what contacts are in the group and the group's name, description, and avatar.
Properties
This endpoint allows you to retrieve a paginated list of all your groups. By default, a maximum of ten groups are shown per page.
Optional attributes
Request
curl -G https://api.protocol.chat/v1/groups \
-H "Authorization: Bearer {token}" \
-d limit=10
Response
{
"has_more": false,
"data": [
{
"id": "l7cGNIBKZiNJ6wqF",
"name": "Plaza Hotel",
"description": "World-renowned.",
"avatar_url": "https://assets.protocol.chat/avatars/plazahotel.jpg",
"conversation_id": "ZYjVAbCE9g5XRlra",
"contacts": [
{
"username": "Hector"
// ...
},
{
"username": "Cedric"
// ...
},
{
"username": "Hester"
// ...
},
{
"username": "Cliff"
// ...
}
],
"created_at": 692233200,
"archived_at": null
},
{
"id": "hSIhXBhNe8X1d8Et"
// ...
}
]
}
This endpoint allows you to create a new group conversation between you and a group of your CityPay contacts.
Required attributes
Optional attributes
Request
curl https://api.protocol.chat/v1/groups \
-H "Authorization: Bearer {token}" \
-d name="Plaza Hotel"
Response
{
"id": "l7cGNIBKZiNJ6wqF",
"name": "Plaza Hotel",
"description": null,
"avatar_url": null,
"conversation_id": "ZYjVAbCE9g5XRlra",
"contacts": [],
"created_at": 692233200,
"archived_at": null
}
This endpoint allows you to retrieve a group by providing the group id. Refer to the list at the top of this page to see which properties are included with group objects.
Request
curl https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
-H "Authorization: Bearer {token}"
Response
{
"id": "l7cGNIBKZiNJ6wqF",
"name": "Plaza Hotel",
"description": "World-renowned.",
"avatar_url": "https://assets.protocol.chat/avatars/plazahotel.jpg",
"conversation_id": "ZYjVAbCE9g5XRlra",
"contacts": [
{
"username": "Hector"
// ...
},
{
"username": "Cedric"
// ...
},
{
"username": "Hester"
// ...
},
{
"username": "Cliff"
// ...
}
],
"created_at": 692233200,
"archived_at": null
}
This endpoint allows you to perform an update on a group. Examples of updates are changing the name, description, and avatar or adding and removing contacts from the group.
Optional attributes
Request
curl -X PUT https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
-H "Authorization: Bearer {token}" \
-d description="The finest in New York."
Response
{
"id": "l7cGNIBKZiNJ6wqF",
"name": "Plaza Hotel",
"description": "The finest in New York.",
"avatar_url": "https://assets.protocol.chat/avatars/plazahotel.jpg",
"conversation_id": "ZYjVAbCE9g5XRlra",
"contacts": [
{
"username": "Hector"
// ...
},
{
"username": "Cedric"
// ...
},
{
"username": "Hester"
// ...
},
{
"username": "Cliff"
// ...
}
],
"created_at": 692233200,
"archived_at": null
},
This endpoint allows you to delete groups. Note: This will permanently delete the group, including the messages — archive it instead if you want to be able to restore it later.
Request
curl -X DELETE https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
-H "Authorization: Bearer {token}"