DOCSEARCHbyAlgolia
Submit Docs

Protocol API Documentation

website·Indexed 31 days ago

https://doc-tuts.vercel.app/

Documentation for the Protocol API, featuring guides on managing contacts, conversations, groups, and messages. Includes technical details on authentication, webhooks, pagination, error handling, and official SDKs for JavaScript and PHP.

Tokens
4.2K
Snippets
36
Records
46
Agent score
72%

What's inside Protocol

  1. Protocol Message Model Reference

    The message model represents the core building block of conversations in Protocol. It includes details about the message content, the sender, and associated metadata.
    {
  "id": "string", // Unique identifier for the message
  "conversation_id": "string", // Unique identifier for the conversation
  "contact": "object", // The contact object for the sender
  "message": "string", // The message content
  "reactions": "array", // Array of reaction objects
  "attachments": "array", // Array of attachment objects
  "read_at": "timestamp", // When the message was read
  "created_at": "timestamp", // When the message was created
  "updated_at": "timestamp" // When the message was last updated
}

  2. Retrieve a specific Protocol group

    Retrieve detailed information about a single group using its unique group ID.
    curl https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \
  -H "Authorization: Bearer {token}"

  3. Authenticate Protocol API requests using OAuth2 (Recommended)

    The recommended method for authenticating with the Protocol API is OAuth2. You must include your access token, found in the Protocol dashboard under API settings, in the request header as a Bearer token.
    curl https://api.protocol.chat/v1/conversations \
  -H "Authorization: Bearer {token}"

  4. Use Protocol SDKs for simplified authentication

    Official Protocol SDKs handle authentication automatically using OAuth2. To use an SDK, retrieve your access token from the Protocol dashboard under API settings and provide it to the client library.

  5. Get started with the Protocol API

    The Protocol API allows you to integrate products into Protocol workflows by accessing contacts, conversations, group messages, and other resources. To begin, create a new application in the developer settings to obtain an API key. You can interact with the API using standard HTTP requests or dedicated client SDKs.

  6. Authenticate Protocol API requests using Basic Authentication

    Basic authentication allows you to use your username and password to authenticate HTTP requests. This method is generally discouraged unless specifically required.
    curl https://api.protocol.chat/v1/conversations \
  -u username:password

  7. Authenticate requests to the Protocol API

    To make requests to the Protocol API, you must use an API key. This key is located in the Protocol dashboard under Settings » API.

  8. Consume and process Protocol webhook events

    When your application receives a webhook request from Protocol, use the type attribute to determine the event that triggered the request. The first part of the event type indicates the payload type (e.g., conversation, message).
    {
  "id": "a056V7R7NmNRjl70",
  "type": "conversation.updated",
  "payload": {
    "id": "WAz8eIbvDR60rouK"
    // ...
  }
}

  9. Register Protocol webhooks

    To receive notifications when events occur in Protocol (such as messages being sent or contacts added), you must register a webhook URL. This is configured in the Protocol dashboard under API settings. You must provide a name for the webhook, a destination URL in your application, and select the specific events you wish to listen for.

  10. Manage paginated responses in the Protocol API

    The Protocol API uses cursor-based pagination for all responses that return a list of objects. By default, responses are limited to 10 results. You can increase this limit up to 100 using the limit parameter.

    Paginated responses wrap the result list in a data attribute and include a has_more boolean attribute to indicate if additional pages of results exist.

  11. List all attachments

    Retrieve a paginated list of attachments. You can optionally filter by a specific conversation or limit the number of results returned. By default, the API returns a maximum of ten attachments per page.
    curl -G https://api.protocol.chat/v1/attachments \
  -H "Authorization: Bearer {token}" \
  -d conversation_id="xgQQXg3hrtjh7AvZ" \
  -d limit=10

  12. Update conversation settings

    Update properties of an existing conversation, such as pinning a message, muting, archiving, or pinning the conversation itself. Supported optional attributes include pinned_message_id (string), is_pinned (boolean), is_muted (boolean), and archived_at (timestamp).
    curl -X PUT https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'is_muted'=true