Groups

Groups are where communities live in Protocol — 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

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

  • Name
    id
    Type
    string
    Description

    Unique identifier for the group.

  • Name
    name
    Type
    string
    Description

    The name for the group.

  • Name
    description
    Type
    string
    Description

    The description for the group.

  • Name
    avatar_url
    Type
    string
    Description

    The avatar image URL for the group.

  • Name
    conversation_id
    Type
    string
    Description

    Unique identifier for the conversation that belongs to the group.

  • Name
    contacts
    Type
    array
    Description

    An array of contact objects that are members of the group.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the group was created.

  • Name
    archived_at
    Type
    timestamp
    Description

    Timestamp of when the group was archived.

GET/v1/groups

List all groups

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

  • Name
    limit
    Type
    integer
    Description

    Limit the number of groups returned.

  • Name
    archived
    Type
    boolean
    Description

    Only show groups that are archived when set to true.

Request

GET
/v1/groups
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"
      // ...
    }
  ]
}
POST/v1/groups

Create a group

This endpoint allows you to create a new group conversation between you and a group of your Protocol contacts.

Required attributes

  • Name
    name
    Type
    string
    Description

    The name for the group.

Optional attributes

  • Name
    description
    Type
    string
    Description

    The description for the group.

  • Name
    avatar_url
    Type
    string
    Description

    The avatar image URL for the group.

  • Name
    contacts
    Type
    array
    Description

    An array of contact objects that are members of the group.

Request

POST
/v1/groups
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
}
GET/v1/groups/:id

Retrieve a group

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

GET
/v1/groups/L7cGNIBKZiNJ6wqF
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
}
PUT/v1/groups/:id

Update a group

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

  • Name
    name
    Type
    string
    Description

    The new name for the group.

  • Name
    description
    Type
    string
    Description

    The new description for the group.

  • Name
    avatar_url
    Type
    string
    Description

    The new avatar image URL for the group.

  • Name
    contacts
    Type
    array
    Description

    An array of contact objects that are members of the group.

  • Name
    archived_at
    Type
    timestamp
    Description

    Timestamp of when the group was archived.

Request

PUT
/v1/groups/L7cGNIBKZiNJ6wqF
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
},
DELETE/v1/groups/:id

Delete a group

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

DELETE
/v1/groups/L7cGNIBKZiNJ6wqF
curl -X DELETE https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
  -H "Authorization: Bearer {token}"