From eb5a58621a418a1aed7c1da5fced1b6d6ca9f194 Mon Sep 17 00:00:00 2001 From: Jesse Wierzbinski Date: Mon, 22 Jul 2024 19:03:38 +0200 Subject: [PATCH] refactor: :fire: Remove template code --- app/attachments/page.mdx | 363 ----------------------------- app/authentication/page.mdx | 41 ---- app/contacts/page.mdx | 394 ------------------------------- app/conversations/page.mdx | 407 -------------------------------- app/errors/page.mdx | 70 ------ app/groups/page.mdx | 448 ------------------------------------ app/introduction/page.mdx | 98 -------- app/messages/page.mdx | 441 ----------------------------------- app/pagination/page.mdx | 63 ----- app/webhooks/page.mdx | 172 -------------- components/Heading.tsx | 2 +- 11 files changed, 1 insertion(+), 2498 deletions(-) delete mode 100644 app/attachments/page.mdx delete mode 100644 app/authentication/page.mdx delete mode 100644 app/contacts/page.mdx delete mode 100644 app/conversations/page.mdx delete mode 100644 app/errors/page.mdx delete mode 100644 app/groups/page.mdx delete mode 100644 app/introduction/page.mdx delete mode 100644 app/messages/page.mdx delete mode 100644 app/pagination/page.mdx delete mode 100644 app/webhooks/page.mdx diff --git a/app/attachments/page.mdx b/app/attachments/page.mdx deleted file mode 100644 index cd36364..0000000 --- a/app/attachments/page.mdx +++ /dev/null @@ -1,363 +0,0 @@ -export const metadata = { - title: 'Attachments', - description: - 'On this page, we’ll dive into the different attachment endpoints you can use to manage attachments programmatically.', -} - -# Attachments - -Attachments are how you share things in Protocol — they allow you to send all sorts of files to your contacts and groups. On this page, we'll dive into the different attachment endpoints you can use to manage attachments programmatically. We'll look at how to query, upload, update, and delete attachments. {{ className: 'lead' }} - -## The attachment model - -The attachment model contains all the information about the files you send to your contacts and groups, including the name, type, and size. - -### Properties - - - - Unique identifier for the attachment. - - - Unique identifier for the message associated with the attachment. - - - The filename for the attachment. - - - The URL for the attached file. - - - The MIME type of the attached file. - - - The file size of the attachment in bytes. - - - Timestamp of when the attachment was created. - - - ---- - -## List all attachments {{ tag: 'GET', label: '/v1/attachments' }} - - - - - This endpoint allows you to retrieve a paginated list of all your attachments (in a conversation if a conversation id is provided). By default, a maximum of ten attachments are shown per page. - - ### Optional attributes - - - - Limit to attachments from a given conversation. - - - Limit the number of attachments returned. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -G https://api.protocol.chat/v1/attachments \ - -H "Authorization: Bearer {token}" \ - -d conversation_id="xgQQXg3hrtjh7AvZ" \ - -d limit=10 - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.attachments.list() - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.attachments.list() - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->attachments->list(); - ``` - - - - ```json {{ title: 'Response' }} - { - "has_more": false, - "data": [ - { - "id": "Nc6yKKMpcxiiFxp6", - "message_id": "LoPsJaMcPBuFNjg1", - "filename": "Invoice_room_service__Plaza_Hotel.pdf", - "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf", - "file_type": "application/pdf", - "file_size": 21352, - "created_at": 692233200 - }, - { - "id": "hSIhXBhNe8X1d8Et" - // ... - } - ] - } - ``` - - - - ---- - -## Create an attachment {{ tag: 'POST', label: '/v1/attachments' }} - - - - - This endpoint allows you to upload a new attachment to a conversation. See the code examples for how to send the file to the Protocol API. - - ### Required attributes - - - - The file you want to add as an attachment. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/attachments \ - -H "Authorization: Bearer {token}" \ - -F file="../Invoice_room_service__Plaza_Hotel.pdf" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.attachments.create({ file }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.attachments.create(file=file) - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->attachments->create([ - 'file' => $file, - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "Nc6yKKMpcxiiFxp6", - "message_id": "LoPsJaMcPBuFNjg1", - "filename": "Invoice_room_service__Plaza_Hotel.pdf", - "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf", - "file_type": "application/pdf", - "file_size": 21352, - "created_at": 692233200 - } - ``` - - - - ---- - -## Retrieve an attachment {{ tag: 'GET', label: '/v1/attachments/:id' }} - - - - - This endpoint allows you to retrieve an attachment by providing the attachment id. Refer to [the list](#the-attachment-model) at the top of this page to see which properties are included with attachment objects. - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.attachments.get('Nc6yKKMpcxiiFxp6') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.attachments.get("Nc6yKKMpcxiiFxp6") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->attachments->get('Nc6yKKMpcxiiFxp6'); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "Nc6yKKMpcxiiFxp6", - "message_id": "LoPsJaMcPBuFNjg1", - "filename": "Invoice_room_service__Plaza_Hotel.pdf", - "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel.pdf", - "file_type": "application/pdf", - "file_size": 21352, - "created_at": 692233200 - } - ``` - - - - ---- - -## Update an attachment {{ tag: 'PUT', label: '/v1/attachments/:id' }} - - - - - This endpoint allows you to perform an update on an attachment. Currently, the only supported type of update is changing the filename. - - ### Optional attributes - - - - The new filename for the attachment. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -X PUT https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \ - -H "Authorization: Bearer {token}" \ - -d filename="Invoice_room_service__Plaza_Hotel_updated.pdf" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.attachments.update('Nc6yKKMpcxiiFxp6', { - filename: 'Invoice_room_service__Plaza_Hotel_updated.pdf', - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.attachments.update("Nc6yKKMpcxiiFxp6", filename="Invoice_room_service__Plaza_Hotel_updated.pdf") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->attachments->update('Nc6yKKMpcxiiFxp6', [ - 'filename' => 'Invoice_room_service__Plaza_Hotel_updated.pdf', - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "Nc6yKKMpcxiiFxp6", - "message_id": "LoPsJaMcPBuFNjg1", - "filename": "Invoice_room_service__Plaza_Hotel.pdf", - "file_url": "https://assets.protocol.chat/attachments/Invoice_room_service__Plaza_Hotel_updated.pdf", - "file_type": "application/pdf", - "file_size": 21352, - "created_at": 692233200 - } - ``` - - - - ---- - -## Delete an attachment {{ tag: 'DELETE', label: '/v1/attachments/:id' }} - - - - - This endpoint allows you to delete attachments. Note: This will permanently delete the file. - - - - - - - ```bash {{ title: 'cURL' }} - curl -X DELETE https://api.protocol.chat/v1/attachments/Nc6yKKMpcxiiFxp6 \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.attachments.delete('Nc6yKKMpcxiiFxp6') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.attachments.delete("Nc6yKKMpcxiiFxp6") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->attachments->delete('Nc6yKKMpcxiiFxp6'); - ``` - - - - - diff --git a/app/authentication/page.mdx b/app/authentication/page.mdx deleted file mode 100644 index 625f0af..0000000 --- a/app/authentication/page.mdx +++ /dev/null @@ -1,41 +0,0 @@ -export const metadata = { - title: 'Authentication', - description: - 'In this guide, we’ll look at how authentication works. Protocol offers two ways to authenticate your API requests: Basic authentication and OAuth2 with a token.', -} - -# Authentication - -You'll need to authenticate your requests to access any of the endpoints in the Protocol API. In this guide, we'll look at how authentication works. Protocol offers two ways to authenticate your API requests: Basic authentication and OAuth2 with a token — OAuth2 is the recommended way. {{ className: 'lead' }} - -## Basic authentication - -With basic authentication, you use your username and password to authenticate your HTTP requests. Unless you have a very good reason, you probably shouldn't use basic auth. Here's how to authenticate using cURL: - -```bash {{ title: 'Example request with basic auth' }} -curl https://api.protocol.chat/v1/conversations \ - -u username:password -``` - -Please don't commit your Protocol password to GitHub! - -## OAuth2 with bearer token - -The recommended way to authenticate with the Protocol API is by using OAuth2. When establishing a connection using OAuth2, you will need your access token — you will find it in the [Protocol dashboard](#) under API settings. Here's how to add the token to the request header using cURL: - -```bash {{ title: 'Example request with bearer token' }} -curl https://api.protocol.chat/v1/conversations \ - -H "Authorization: Bearer {token}" -``` - -Always keep your token safe and reset it if you suspect it has been compromised. - -## Using an SDK - -If you use one of our official SDKs, you won't have to worry about any of the above — fetch your access token from the [Protocol dashboard](#) under API settings, and the client library will take care of the rest. All the client libraries use OAuth2 behind the scenes. - -
- -
diff --git a/app/contacts/page.mdx b/app/contacts/page.mdx deleted file mode 100644 index b75afa9..0000000 --- a/app/contacts/page.mdx +++ /dev/null @@ -1,394 +0,0 @@ -export const metadata = { - title: 'Contacts', - description: - 'On this page, we’ll dive into the different contact endpoints you can use to manage contacts programmatically.', -} - -# Contacts - -As the name suggests, contacts are a core part of Protocol — the very reason Protocol exists is so you can have secure conversations with your contacts. On this page, we'll dive into the different contact endpoints you can use to manage contacts programmatically. We'll look at how to query, create, update, and delete contacts. {{ className: 'lead' }} - -## The contact model - -The contact model contains all the information about your contacts, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the contact and information about when they were last active on Protocol. - -### Properties - - - - Unique identifier for the contact. - - - The username for the contact. - - - The phone number for the contact. - - - The avatar image URL for the contact. - - - The contact display name in the contact list. By default, this is just the - username. - - - Unique identifier for the conversation associated with the contact. - - - Timestamp of when the contact was last active on the platform. - - - Timestamp of when the contact was created. - - - ---- - -## List all contacts {{ tag: 'GET', label: '/v1/contacts' }} - - - - - This endpoint allows you to retrieve a paginated list of all your contacts. By default, a maximum of ten contacts are shown per page. - - ### Optional attributes - - - - Limit the number of contacts returned. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -G https://api.protocol.chat/v1/contacts \ - -H "Authorization: Bearer {token}" \ - -d active=true \ - -d limit=10 - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.contacts.list() - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.contacts.list() - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->contacts->list(); - ``` - - - - ```json {{ title: 'Response' }} - { - "has_more": false, - "data": [ - { - "id": "WAz8eIbvDR60rouK", - "username": "FrankMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg", - "display_name": null, - "conversation_id": "xgQQXg3hrtjh7AvZ", - "last_active_at": 705103200, - "created_at": 692233200 - }, - { - "id": "hSIhXBhNe8X1d8Et" - // ... - } - ] - } - ``` - - - - ---- - -## Create a contact {{ tag: 'POST', label: '/v1/contacts' }} - - - - - This endpoint allows you to add a new contact to your contact list in Protocol. To add a contact, you must provide their Protocol username and phone number. - - ### Required attributes - - - - The username for the contact. - - - The phone number for the contact. - - - - ### Optional attributes - - - - The avatar image URL for the contact. - - - The contact display name in the contact list. By default, this is just the username. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/contacts \ - -H "Authorization: Bearer {token}" \ - -d username="FrankMcCallister" \ - -d phone_number="1-800-759-3000" \ - -d avatar_url="https://assets.protocol.chat/avatars/frank.jpg" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.contacts.create({ - username: 'FrankMcCallister', - phone_number: '1-800-759-3000', - avatar_url: 'https://assets.protocol.chat/avatars/frank.jpg', - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.contacts.create( - username="FrankMcCallister", - phone_number="1-800-759-3000", - avatar_url="https://assets.protocol.chat/avatars/frank.jpg", - ) - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->contacts->create([ - 'username' => 'FrankMcCallister', - 'phone_number' => '1-800-759-3000', - 'avatar_url' => 'https://assets.protocol.chat/avatars/frank.jpg', - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "WAz8eIbvDR60rouK", - "username": "FrankMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg", - "display_name": null, - "conversation_id": "xgQQXg3hrtjh7AvZ", - "last_active_at": null, - "created_at": 692233200 - } - ``` - - - - ---- - -## Retrieve a contact {{ tag: 'GET', label: '/v1/contacts/:id' }} - - - - - This endpoint allows you to retrieve a contact by providing their Protocol id. Refer to [the list](#the-contact-model) at the top of this page to see which properties are included with contact objects. - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.contacts.get('WAz8eIbvDR60rouK') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.contacts.get("WAz8eIbvDR60rouK") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->contacts->get('WAz8eIbvDR60rouK'); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "WAz8eIbvDR60rouK", - "username": "FrankMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg", - "display_name": null, - "conversation_id": "xgQQXg3hrtjh7AvZ", - "last_active_at": 705103200, - "created_at": 692233200 - } - ``` - - - - ---- - -## Update a contact {{ tag: 'PUT', label: '/v1/contacts/:id' }} - - - - - This endpoint allows you to perform an update on a contact. Currently, the only attribute that can be updated on contacts is the `display_name` attribute which controls how a contact appears in your contact list in Protocol. - - ### Optional attributes - - - - The contact display name in the contact list. By default, this is just the username. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -X PUT https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \ - -H "Authorization: Bearer {token}" \ - -d display_name="UncleFrank" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.contacts.update('WAz8eIbvDR60rouK', { - display_name: 'UncleFrank', - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.contacts.update("WAz8eIbvDR60rouK", display_name="UncleFrank") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->contacts->update('WAz8eIbvDR60rouK', [ - 'display_name' => 'UncleFrank', - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "WAz8eIbvDR60rouK", - "username": "FrankMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg", - "display_name": "UncleFrank", - "conversation_id": "xgQQXg3hrtjh7AvZ", - "last_active_at": 705103200, - "created_at": 692233200 - } - ``` - - - - ---- - -## Delete a contact {{ tag: 'DELETE', label: '/v1/contacts/:id' }} - - - - - This endpoint allows you to delete contacts from your contact list in Protocol. Note: This will also delete your conversation with the given contact. - - - - - - - ```bash {{ title: 'cURL' }} - curl -X DELETE https://api.protocol.chat/v1/contacts/WAz8eIbvDR60rouK \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.contacts.delete('WAz8eIbvDR60rouK') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.contacts.delete("WAz8eIbvDR60rouK") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->contacts->delete('WAz8eIbvDR60rouK'); - ``` - - - - - diff --git a/app/conversations/page.mdx b/app/conversations/page.mdx deleted file mode 100644 index 87fae52..0000000 --- a/app/conversations/page.mdx +++ /dev/null @@ -1,407 +0,0 @@ -export const metadata = { - title: 'Conversations', - description: - 'On this page, we’ll dive into the different conversation endpoints you can use to manage conversations programmatically.', -} - -# Conversations - -Conversations are an essential part of Protocol — they are the containers for the messages between you, your contacts, and groups. On this page, we’ll dive into the different conversation endpoints you can use to manage conversations programmatically. We'll look at how to query, create, update, and delete conversations. {{ className: 'lead' }} - -## The conversation model - -The conversation model contains all the information about the conversations between you and your contacts. In addition, conversations can also be group-based with more than one contact, they can have a pinned message, and they can be muted. - -### Properties - - - - Unique identifier for the conversation. - - - Unique identifier for the other contact in the conversation. - - - Unique identifier for the group that the conversation belongs to. - - - Unique identifier for the pinned message. - - - Whether or not the conversation has been pinned. - - - Whether or not the conversation has been muted. - - - Timestamp of when the conversation was last active. - - - Timestamp of when the conversation was last opened by the authenticated - user. - - - Timestamp of when the conversation was created. - - - Timestamp of when the conversation was archived. - - - ---- - -## List all conversations {{ tag: 'GET', label: '/v1/conversations' }} - - - - - This endpoint allows you to retrieve a paginated list of all your conversations. By default, a maximum of ten conversations are shown per page. - - ### Optional attributes - - - - Limit the number of conversations returned. - - - Only show conversations that are muted when set to `true`. - - - Only show conversations that are archived when set to `true`. - - - Only show conversations that are pinned when set to `true`. - - - Only show conversations for the specified group. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -G https://api.protocol.chat/v1/conversations \ - -H "Authorization: Bearer {token}" \ - -d limit=10 - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.conversations.list() - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.conversations.list() - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->conversations->list(); - ``` - - - - ```json {{ title: 'Response' }} - { - "has_more": false, - "data": [ - { - "id": "xgQQXg3hrtjh7AvZ", - "contact_id": "WAz8eIbvDR60rouK", - "group_id": null, - "pinned_message_id": null, - "is_pinned": false, - "is_muted": false, - "last_active_at": 705103200, - "last_opened_at": 705103200, - "created_at": 692233200, - "archived_at": null - }, - { - "id": "hSIhXBhNe8X1d8Et" - // ... - } - ] - } - ``` - - - - ---- - -## Create a conversation {{ tag: 'POST', label: '/v1/conversations' }} - - - - - This endpoint allows you to add a new conversation between you and a contact or group. A contact or group id is required to create a conversation. - - ### Required attributes - - - - Unique identifier for the other contact in the conversation. - - - Unique identifier for the group that the conversation belongs to. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/conversations \ - -H "Authorization: Bearer {token}" \ - -d 'contact_id'="WAz8eIbvDR60rouK" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.conversations.create({ - contact_id: 'WAz8eIbvDR60rouK', - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.conversations.create(contact_id="WAz8eIbvDR60rouK") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->conversations->create([ - 'contact_id' => 'WAz8eIbvDR60rouK', - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "xgQQXg3hrtjh7AvZ", - "contact_id": "WAz8eIbvDR60rouK", - "group_id": null, - "pinned_message_id": null, - "is_pinned": false, - "is_muted": false, - "last_active_at": null, - "last_opened_at": null, - "created_at": 692233200, - "archived_at": null - } - ``` - - - - ---- - -## Retrieve a conversation {{ tag: 'GET', label: '/v1/conversations/:id' }} - - - - - This endpoint allows you to retrieve a conversation by providing the conversation id. Refer to [the list](#the-conversation-model) at the top of this page to see which properties are included with conversation objects. - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.conversations.get('xgQQXg3hrtjh7AvZ') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.conversations.get("xgQQXg3hrtjh7AvZ") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->conversations->get('xgQQXg3hrtjh7AvZ'); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "xgQQXg3hrtjh7AvZ", - "contact_id": "WAz8eIbvDR60rouK", - "group_id": null, - "pinned_message_id": null, - "is_pinned": false, - "is_muted": false, - "last_active_at": 705103200, - "last_opened_at": 705103200, - "created_at": 692233200, - "archived_at": null - } - ``` - - - - ---- - -## Update a conversation {{ tag: 'PUT', label: '/v1/conversations/:id' }} - - - - - This endpoint allows you to perform an update on a conversation. Examples of updates are pinning a message, muting or archiving the conversation, or pinning the conversation itself. - - ### Optional attributes - - - - Unique identifier for the pinned message. - - - Whether or not the conversation has been pinned. - - - Whether or not the conversation has been muted. - - - Timestamp of when the conversation was archived. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -X PUT https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \ - -H "Authorization: Bearer {token}" \ - -d 'is_muted'=true - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.conversations.update('xgQQXg3hrtjh7AvZ', { - is_muted: true, - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.conversations.update("xgQQXg3hrtjh7AvZ", is_muted=True) - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->conversations->update('xgQQXg3hrtjh7AvZ', [ - 'is_muted' => true, - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "xgQQXg3hrtjh7AvZ", - "contact_id": "WAz8eIbvDR60rouK", - "group_id": null, - "pinned_message_id": null, - "is_pinned": false, - "is_muted": true, - "last_active_at": 705103200, - "last_opened_at": 705103200, - "created_at": 692233200, - "archived_at": null - } - ``` - - - - ---- - -## Delete a conversation {{ tag: 'DELETE', label: '/v1/conversations/:id' }} - - - - - This endpoint allows you to delete your conversations in Protocol. Note: This will permanently delete the conversation and all its messages — archive it instead if you want to be able to restore it later. - - - - - - - ```bash {{ title: 'cURL' }} - curl -X DELETE https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.conversations.delete('xgQQXg3hrtjh7AvZ') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.conversations.delete("xgQQXg3hrtjh7AvZ") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->conversations->delete('xgQQXg3hrtjh7AvZ'); - ``` - - - - - diff --git a/app/errors/page.mdx b/app/errors/page.mdx deleted file mode 100644 index 15f070b..0000000 --- a/app/errors/page.mdx +++ /dev/null @@ -1,70 +0,0 @@ -export const metadata = { - title: 'Errors', - description: - 'In this guide, we will talk about what happens when something goes wrong while you work with the API.', -} - -# Errors - -In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen, and mostly they will be yours, not ours. Let's look at some status codes and error types you might encounter. {{ className: 'lead' }} - -You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). - - - Before reaching out to support with an error, please be aware that 99% of all - reported errors are, in fact, user errors. Therefore, please carefully check - your code before contacting Protocol support. - - ---- - -## Status codes - -Here is a list of the different categories of status codes returned by the Protocol API. Use these to understand if a request was successful. - - - - A 2xx status code indicates a successful response. - - - A 4xx status code indicates a client error — this means it's a _you_ - problem. - - - A 5xx status code indicates a server error — you won't be seeing these. - - - ---- - -## Error types - - - - - Whenever a request is unsuccessful, the Protocol API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable. - - Here is a list of the two error types supported by the Protocol API — use these to understand what you have done wrong. - - - - This means that we made an error, which is highly speculative and unlikely. - - - This means that you made an error, which is much more likely. - - - - - - - ```bash {{ title: "Error response" }} - { - "type": "api_error", - "message": "No way this is happening!?", - "documentation_url": "https://protocol.chat/docs/errors/api_error" - } - ``` - - - diff --git a/app/groups/page.mdx b/app/groups/page.mdx deleted file mode 100644 index e304787..0000000 --- a/app/groups/page.mdx +++ /dev/null @@ -1,448 +0,0 @@ -export const metadata = { - title: 'Groups', - description: - 'On this page, we’ll dive into the different group endpoints you can use to manage groups programmatically.', -} - -# 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. {{ className: 'lead' }} - -## 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 - - - - Unique identifier for the group. - - - The name for the group. - - - The description for the group. - - - The avatar image URL for the group. - - - Unique identifier for the conversation that belongs to the group. - - - An array of contact objects that are members of the group. - - - Timestamp of when the group was created. - - - Timestamp of when the group was archived. - - - ---- - -## List all groups {{ tag: 'GET', label: '/v1/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 - - - - Limit the number of groups returned. - - - Only show groups that are archived when set to `true`. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -G https://api.protocol.chat/v1/groups \ - -H "Authorization: Bearer {token}" \ - -d limit=10 - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.groups.list() - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.groups.list() - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->groups->list(); - ``` - - - - ```json {{ title: '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" - // ... - } - ] - } - ``` - - - - ---- - -## Create a group {{ tag: 'POST', label: '/v1/groups' }} - - - - - This endpoint allows you to create a new group conversation between you and a group of your Protocol contacts. - - ### Required attributes - - - - The name for the group. - - - - ### Optional attributes - - - - The description for the group. - - - The avatar image URL for the group. - - - An array of contact objects that are members of the group. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/groups \ - -H "Authorization: Bearer {token}" \ - -d name="Plaza Hotel" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.groups.create({ - name: 'Plaza Hotel', - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.groups.create(name="Plaza Hotel") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->groups->create([ - 'name' => 'Plaza Hotel', - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "l7cGNIBKZiNJ6wqF", - "name": "Plaza Hotel", - "description": null, - "avatar_url": null, - "conversation_id": "ZYjVAbCE9g5XRlra", - "contacts": [], - "created_at": 692233200, - "archived_at": null - } - ``` - - - - ---- - -## Retrieve a group {{ tag: 'GET', label: '/v1/groups/:id' }} - - - - - This endpoint allows you to retrieve a group by providing the group id. Refer to [the list](#the-group-model) at the top of this page to see which properties are included with group objects. - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.groups.get('L7cGNIBKZiNJ6wqF') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.groups.get("L7cGNIBKZiNJ6wqF") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->groups->get('L7cGNIBKZiNJ6wqF'); - ``` - - - - ```json {{ title: '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 - } - ``` - - - - ---- - -## Update a group {{ tag: 'PUT', label: '/v1/groups/:id' }} - - - - - 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 - - - - The new name for the group. - - - The new description for the group. - - - The new avatar image URL for the group. - - - An array of contact objects that are members of the group. - - - Timestamp of when the group was archived. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -X PUT https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \ - -H "Authorization: Bearer {token}" \ - -d description="The finest in New York." - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.groups.update('L7cGNIBKZiNJ6wqF', { - description: 'The finest in New York.', - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.groups.update("L7cGNIBKZiNJ6wqF", description="The finest in New York.") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->groups->update('L7cGNIBKZiNJ6wqF', [ - 'description' => 'The finest in New York.', - ]); - ``` - - - - ```json {{ title: '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 a group {{ tag: 'DELETE', label: '/v1/groups/:id' }} - - - - - 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. - - - - - - - ```bash {{ title: 'cURL' }} - curl -X DELETE https://api.protocol.chat/v1/groups/L7cGNIBKZiNJ6wqF \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.groups.delete('L7cGNIBKZiNJ6wqF') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.groups.delete("L7cGNIBKZiNJ6wqF") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->groups->delete('L7cGNIBKZiNJ6wqF'); - ``` - - - - - diff --git a/app/introduction/page.mdx b/app/introduction/page.mdx deleted file mode 100644 index 7bf8aea..0000000 --- a/app/introduction/page.mdx +++ /dev/null @@ -1,98 +0,0 @@ -export const metadata = { - title: 'Quickstart', - description: - 'This guide will get you all set up and ready to use the Protocol API. We’ll cover how to get started an API client and how to make your first API request.', -} - -# Quickstart - -This guide will get you all set up and ready to use the Protocol API. We'll cover how to get started using one of our API clients and how to make your first API request. We'll also look at where to go next to find all the information you need to take full advantage of our powerful REST API. {{ className: 'lead' }} - - - Before you can make requests to the Protocol API, you will need to grab your - API key from your dashboard. You find it under [Settings » API](#). - - -## Choose your client - -Before making your first API request, you need to pick which API client you will use. In addition to good ol' cURL HTTP requests, Protocol offers clients for JavaScript, Python, and PHP. In the following example, you can see how to install each client. - - - -```bash {{ title: 'cURL' }} -# cURL is most likely already installed on your machine -curl --version -``` - -```bash {{ language: 'js' }} -# Install the Protocol JavaScript SDK -npm install @example/protocol-api --save -``` - -```bash {{ language: 'python' }} -# Install the Protocol Python SDK -pip install protocol_api -``` - -```bash {{ language: 'php' }} -# Install the Protocol PHP SDK -composer require protocol/sdk -``` - - - -
- -
- -## Making your first API request - -After picking your preferred client, you are ready to make your first call to the Protocol API. Below, you can see how to send a GET request to the Conversations endpoint to get a list of all your conversations. In the cURL example, results are limited to ten conversations, the default page length for each client. - - - -```bash {{ title: 'cURL' }} -curl -G https://api.protocol.chat/v1/conversations \ - -H "Authorization: Bearer {token}" \ - -d limit=10 -``` - -```js -import ApiClient from '@example/protocol-api' - -const client = new ApiClient(token) - -await client.conversations.list() -``` - -```python -from protocol_api import ApiClient - -client = ApiClient(token) - -client.conversations.list() -``` - -```php -$client = new \Protocol\ApiClient($token); - -$client->conversations->list(); -``` - - - -
- -
- -## What's next? - -Great, you're now set up with an API client and have made your first request to the API. Here are a few links that might be handy as you venture further into the Protocol API: - -- [Grab your API key from the Protocol dashboard](#) -- [Check out the Conversations endpoint](/conversations) -- [Learn about the different error messages in Protocol](/errors) diff --git a/app/messages/page.mdx b/app/messages/page.mdx deleted file mode 100644 index e3cbca0..0000000 --- a/app/messages/page.mdx +++ /dev/null @@ -1,441 +0,0 @@ -export const metadata = { - title: 'Messages', - description: - 'On this page, we’ll dive into the different message endpoints you can use to manage messages programmatically.', -} - -# Messages - -Messages are what conversations are made of in Protocol — they are the basic building blocks of your conversations with your Protocol contacts. On this page, we'll dive into the different message endpoints you can use to manage messages programmatically. We'll look at how to query, send, update, and delete messages. {{ className: 'lead' }} - -## The message model - -The message model contains all the information about the messages and attachments you send to your contacts and groups, including how your contacts have reacted to them. - -### Properties - - - - Unique identifier for the message. - - - Unique identifier for the conversation the message belongs to. - - - The contact object for the contact who sent the message. - - - The message content. - - - An array of reaction objects associated with the message. - - - An array of attachment objects associated with the message. - - - Timestamp of when the message was read. - - - Timestamp of when the message was created. - - - Timestamp of when the message was last updated. - - - ---- - -## List all messages {{ tag: 'GET', label: '/v1/messages' }} - - - - - This endpoint allows you to retrieve a paginated list of all your messages (in a conversation if a conversation id is provided). By default, a maximum of ten messages are shown per page. - - ### Optional attributes - - - - Limit to messages from a given conversation. - - - Limit the number of messages returned. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -G https://api.protocol.chat/v1/messages \ - -H "Authorization: Bearer {token}" \ - -d conversation_id=xgQQXg3hrtjh7AvZ \ - -d limit=10 - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.messages.list() - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.messages.list() - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->messages->list(); - ``` - - - - ```json {{ title: 'Response' }} - { - "has_more": false, - "data": [ - { - "id": "SIuAFUNKdSYHZF2w", - "conversation_id": "xgQQXg3hrtjh7AvZ", - "contact": { - "id": "WAz8eIbvDR60rouK", - "username": "KevinMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg", - "last_active_at": 705103200, - "created_at": 692233200 - }, - "message": "It’s a nice night for a neck injury.", - "reactions": [], - "attachments": [], - "read_at": 705103200, - "created_at": 692233200, - "updated_at": 692233200 - }, - { - "id": "hSIhXBhNe8X1d8Et", - // .. - } - ] - } - ``` - - - - ---- - -## Send a message {{ tag: 'POST', label: '/v1/messages' }} - - - - - This endpoint allows you to send a new message to one of your conversations. - - ### Required attributes - - - - Unique identifier for the conversation the message belongs to. - - - The message content. - - - - ### Optional attributes - - - - An array of attachment objects associated with the message. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/messages \ - -H "Authorization: Bearer {token}" \ - -d conversation_id="xgQQXg3hrtjh7AvZ" \ - -d message="You’re what the French call ‘les incompetents.’" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.messages.send({ - conversation_id: 'xgQQXg3hrtjh7AvZ', - message: 'You’re what the French call ‘les incompetents.’', - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.messages.send( - conversation_id="xgQQXg3hrtjh7AvZ", - message="You’re what the French call ‘les incompetents.’", - ) - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->messages->send([ - 'conversation_id' => 'xgQQXg3hrtjh7AvZ', - 'message' => 'You’re what the French call ‘les incompetents.’', - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "gWqY86BMFRiH5o11", - "conversation_id": "xgQQXg3hrtjh7AvZ", - "contact": { - "id": "inEIRvzjC6YLMX3o", - "username": "LinnieMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/linnie.jpg", - "last_active_at": 705103200, - "created_at": 692233200 - }, - "message": "You’re what the French call ‘les incompetents.’", - "reactions": [], - "attachments": [], - "read_at": null, - "created_at": 692233200, - "updated_at": null - } - ``` - - - - ---- - -## Retrieve a message {{ tag: 'GET', label: '/v1/messages/:id' }} - - - - - This endpoint allows you to retrieve a message by providing the message id. Refer to [the list](#the-message-model) at the top of this page to see which properties are included with message objects. - - - - - - - ```bash {{ title: 'cURL' }} - curl https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.messages.get('SIuAFUNKdSYHZF2w') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.messages.get("SIuAFUNKdSYHZF2w") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->messages->get('SIuAFUNKdSYHZF2w'); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "SIuAFUNKdSYHZF2w", - "conversation_id": "xgQQXg3hrtjh7AvZ", - "contact": { - "id": "WAz8eIbvDR60rouK", - "username": "KevinMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/kevin.jpg", - "last_active_at": 705103200, - "created_at": 692233200 - }, - "message": "I’m traveling with my dad. He’s at a meeting. I hate meetings.", - "reactions": [], - "attachments": [], - "read_at": 705103200, - "created_at": 692233200, - "updated_at": 692233200 - } - ``` - - - - ---- - -## Update a message {{ tag: 'PUT', label: '/v1/messages/:id' }} - - - - - This endpoint allows you to perform an update on a message. Examples of updates are adding a reaction, editing the message, or adding an attachment. - - ### Optional attributes - - - - The message content. - - - An array of reaction objects associated with the message. - - - An array of attachment objects associated with the message. - - - - - - - - - ```bash {{ title: 'cURL' }} - curl -X PUT https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \ - -H "Authorization: Bearer {token}" \ - -d reactions[red_angry_face][]="KateMcCallister" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.messages.update('SIuAFUNKdSYHZF2w', { - reactions: { - red_angry_face: ['KateMcCallister'] - } - }) - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.messages.update("SIuAFUNKdSYHZF2w", - reactions={"red_angry_face": ["KateMcCallister"]}) - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->messages->update('SIuAFUNKdSYHZF2w', [ - 'reactions' => [ - 'red_angry_face' => ['KateMcCallister'], - ], - ]); - ``` - - - - ```json {{ title: 'Response' }} - { - "id": "SIuAFUNKdSYHZF2w", - "conversation_id": "xgQQXg3hrtjh7AvZ", - "contact": { - "id": "WAz8eIbvDR60rouK", - "username": "KevinMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/buzzboy.jpg", - "last_active_at": 705103200, - "created_at": 692233200 - }, - "message": "I'm not apologizing. I'd rather kiss a toilet seat.", - "reactions": [ - { - "red_angry_face": [ - "KateMcCallister" - ] - } - ], - "attachments": [], - "read_at": 705103200, - "created_at": 692233200, - "updated_at": 692233200 - } - ``` - - - - ---- - -## Delete a message {{ tag: 'DELETE', label: '/v1/messages/:id' }} - - - - - This endpoint allows you to delete messages from your conversations. Note: This will permanently delete the message. - - - - - - - ```bash {{ title: 'cURL' }} - curl -X DELETE https://api.protocol.chat/v1/messages/SIuAFUNKdSYHZF2w \ - -H "Authorization: Bearer {token}" - ``` - - ```js - import ApiClient from '@example/protocol-api' - - const client = new ApiClient(token) - - await client.messages.delete('SIuAFUNKdSYHZF2w') - ``` - - ```python - from protocol_api import ApiClient - - client = ApiClient(token) - - client.messages.delete("SIuAFUNKdSYHZF2w") - ``` - - ```php - $client = new \Protocol\ApiClient($token); - - $client->messages->delete('SIuAFUNKdSYHZF2w'); - ``` - - - - - diff --git a/app/pagination/page.mdx b/app/pagination/page.mdx deleted file mode 100644 index 8bec705..0000000 --- a/app/pagination/page.mdx +++ /dev/null @@ -1,63 +0,0 @@ -export const metadata = { - title: 'Pagination', - description: - 'In this guide, we will look at how to work with paginated responses when querying the Protocol API', -} - -# Pagination - -In this guide, we will look at how to work with paginated responses when querying the Protocol API. By default, all responses limit results to ten. However, you can go as high as 100 by adding a `limit` parameter to your requests. If you are using one of the official Protocol API client libraries, you don't need to worry about pagination, as it's all being taken care of behind the scenes. {{ className: 'lead' }} - -When an API response returns a list of objects, no matter the amount, pagination is supported. In paginated responses, objects are nested in a `data` attribute and have a `has_more` attribute that indicates whether you have reached the end of the last page. You can use the `starting_after` and `endding_before` query parameters to browse pages. - -## Example using cursors - - - - - In this example, we request the page that starts after the conversation with id `s4WycXedwhQrEFuM`. As a result, we get a list of three conversations and can tell by the `has_more` attribute that we have reached the end of the resultset. - - - - The last ID on the page you're currently on when you want to fetch the next page. - - - The first ID on the page you're currently on when you want to fetch the previous page. - - - Limit the number of items returned. - - - - - - - ```bash {{ title: 'Manual pagination using cURL' }} - curl -G https://api.protocol.chat/v1/conversations \ - -H "Authorization: Bearer {token}" \ - -d starting_after="s4WycXedwhQrEFuM" \ - -d limit=10 - ``` - - ```json {{ title: 'Paginated response' }} - { - "has_more": false, - "data": [ - { - "id": "WAz8eIbvDR60rouK", - // ... - }, - { - "id": "hSIhXBhNe8X1d8Et" - // ... - }, - { - "id": "fbwYwpi9C2ybt6Yb" - // ... - } - ] - } - ``` - - - diff --git a/app/webhooks/page.mdx b/app/webhooks/page.mdx deleted file mode 100644 index d8a568d..0000000 --- a/app/webhooks/page.mdx +++ /dev/null @@ -1,172 +0,0 @@ -export const metadata = { - title: 'Webhooks', - description: - 'In this guide, we will look at how to register and consume webhooks to integrate your app with Protocol.', -} - -# Webhooks - -In this guide, we will look at how to register and consume webhooks to integrate your app with Protocol. With webhooks, your app can know when something happens in Protocol, such as someone sending a message or adding a contact. {{ className: 'lead' }} - -## Registering webhooks - -To register a new webhook, you need to have a URL in your app that Protocol can call. You can configure a new webhook from the Protocol dashboard under [API settings](#). Give your webhook a name, pick the [events](#event-types) you want to listen for, and add your URL. - -Now, whenever something of interest happens in your app, a webhook is fired off by Protocol. In the next section, we'll look at how to consume webhooks. - -## Consuming webhooks - -When your app receives a webhook request from Protocol, check the `type` attribute to see what event caused it. The first part of the event type will tell you the payload type, e.g., a conversation, message, etc. - -```json {{ title: 'Example webhook payload' }} -{ - "id": "a056V7R7NmNRjl70", - "type": "conversation.updated", - "payload": { - "id": "WAz8eIbvDR60rouK" - // ... - } -} -``` - -In the example above, a conversation was `updated`, and the payload type is a `conversation`. - -
- -
- ---- - -## Event types - - - - - - - A new contact was created. - - - An existing contact was updated. - - - A contact was successfully deleted. - - - A new conversation was created. - - - An existing conversation was updated. - - - A conversation was successfully deleted. - - - A new message was created. - - - An existing message was updated. - - - A message was successfully deleted. - - - A new group was created. - - - An existing group was updated. - - - A group was successfully deleted. - - - A new attachment was created. - - - An existing attachment was updated. - - - An attachment was successfully deleted. - - - - - - - ```json {{ 'title': 'Example payload' }} - { - "id": "a056V7R7NmNRjl70", - "type": "message.updated", - "payload": { - "id": "SIuAFUNKdSYHZF2w", - "conversation_id": "xgQQXg3hrtjh7AvZ", - "contact": { - "id": "WAz8eIbvDR60rouK", - "username": "KevinMcCallister", - "phone_number": "1-800-759-3000", - "avatar_url": "https://assets.protocol.chat/avatars/kevin.jpg", - "last_active_at": 705103200, - "created_at": 692233200 - }, - "message": "I’m traveling with my dad. He’s at a meeting. I hate meetings.", - "reactions": [], - "attachments": [], - "read_at": 705103200, - "created_at": 692233200, - "updated_at": 692233200 - } - } - ``` - - - - ---- - -## Security - -To know for sure that a webhook was, in fact, sent by Protocol instead of a malicious actor, you can verify the request signature. Each webhook request contains a header named `x-protocol-signature`, and you can verify this signature by using your secret webhook key. The signature is an HMAC hash of the request payload hashed using your secret key. Here is an example of how to verify the signature in your app: - - - -```js -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 -} -``` - -```python -from flask import request -import hashlib -import hmac - -signature = request.headers.get("x-protocol-signature") -hash = hmac.new(bytes(secret, "ascii"), bytes(payload, "ascii"), hashlib.sha256) - -if hash.hexdigest() == signature: - # Request is verified -else: - # Request could not be verified -``` - -```php -$signature = $request['headers']['x-protocol-signature']; -$hash = hash_hmac('sha256', $payload, $secret); - -if (hash_equals($hash, $signature)) { - // Request is verified -} else { - // Request could not be verified -} -``` - - - -If your generated signature matches the `x-protocol-signature` header, you can be sure that the request was truly coming from Protocol. It's essential to keep your secret webhook key safe — otherwise, you can no longer be sure that a given webhook was sent by Protocol. Don't commit your secret webhook key to GitHub! diff --git a/components/Heading.tsx b/components/Heading.tsx index fd194f5..e9f31b2 100644 --- a/components/Heading.tsx +++ b/components/Heading.tsx @@ -61,7 +61,7 @@ function Anchor({ > {inView && (
-
+