DOCSEARCHbyAlgolia
Submit Docs

Protocol API Documentation

website·Indexed 40 days ago

https://protocol.tailwindui.com/

Documentation for the Protocol API, featuring guides on authentication, webhooks, and pagination. It provides details on managing contacts, conversations, messages, groups, and attachments, with official SDKs available for JavaScript and PHP.

Tokens
4.3K
Snippets
35
Records
45
Agent score
63%

What's inside Protocol

  1. Understand the Protocol Message model

    The message model represents the core building block of conversations in Protocol. It contains details about the message content, the sender, timestamps, and associated metadata like reactions and attachments.
    {
  "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. Interact with the Protocol API using official SDKs

    The recommended method for interacting with the Protocol API is through official SDKs. Protocol provides fine-tuned libraries for the following languages to optimize the API consumption experience: JavaScript (Node.js), Ruby, PHP, Python, and Go.

  3. 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}"

  4. Verify Protocol webhook request signatures

    To ensure a webhook request was sent by Protocol and not a malicious actor, verify the x-protocol-signature header. The signature is an HMAC SHA256 hash of the request payload using your secret webhook key.

    Security Warning: Never commit your secret webhook key to version control (e.g., GitHub).

    const signature = req.headers['x-protocol-signature']
const hash = crypto.createHmac('sha256', secret).update(payload).digest('hex')

if (hash === signature) {
  // Request is verified
} else {
  // Request could not be verified
}

  5. Register webhooks in the Protocol dashboard

    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.

  6. Use Protocol official SDKs for authentication

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

  7. Get started with the Protocol API

    To integrate your product with Protocol, you must first create a new application in your developer settings to obtain an API key. You can then interact with the platform using the provided HTTP APIs or dedicated client SDKs. Once an integration is complete, it can be published to the Protocol integrations directory.

  8. 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

  9. Consume Protocol webhook events

    When your application receives a webhook request, 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"
    // ...
  }
}

  10. Handle 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 items. Paginated responses wrap the result set in a data array and include a has_more boolean attribute to indicate if more pages are available.

    To navigate pages, use the following query parameters:

    • limit (integer): The number of items to return. Maximum value is 100.
    • starting_after (string): The ID of the last item on the current page to fetch the next page.
    • ending_before (string): The ID of the first item on the current page to fetch the previous page.
    {
  "has_more": false,
  "data": [
    {
      "id": "WAz8eIbvDR60rouK",
      // ...
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    },
    {
      "id": "fbwYwpi9C2ybt6Yb"
      // ...
    }
  ]
}

  11. 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. The key is passed in the HTTP request header as a Bearer token.

  12. Authenticate Protocol API requests using OAuth2 (Recommended)

    The recommended method for authenticating with the Protocol API is using OAuth2 with a bearer token. You can obtain your access token from the Protocol dashboard under API settings. The token must be included in the Authorization request header.
    curl https://api.protocol.chat/v1/conversations \
  -H "Authorization: Bearer {token}"