mirror of
https://github.com/versia-pub/docs.git
synced 2025-12-06 06:18:19 +01:00
refactor: 🔥 Remove template code
This commit is contained in:
Jesse Wierzbinski
parent
cf4f4ee727
commit
eb5a58621a
|
|
@ -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
|
||||
|
||||
<Properties>
|
||||
<Property name="id" type="string">
|
||||
Unique identifier for the attachment.
|
||||
</Property>
|
||||
<Property name="message_id" type="string">
|
||||
Unique identifier for the message associated with the attachment.
|
||||
</Property>
|
||||
<Property name="filename" type="string">
|
||||
The filename for the attachment.
|
||||
</Property>
|
||||
<Property name="file_url" type="string">
|
||||
The URL for the attached file.
|
||||
</Property>
|
||||
<Property name="file_type" type="string">
|
||||
The MIME type of the attached file.
|
||||
</Property>
|
||||
<Property name="file_size" type="integer">
|
||||
The file size of the attachment in bytes.
|
||||
</Property>
|
||||
<Property name="created_at" type="timestamp">
|
||||
Timestamp of when the attachment was created.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
---
|
||||
|
||||
## List all attachments {{ tag: 'GET', label: '/v1/attachments' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="conversation_id" type="string">
|
||||
Limit to attachments from a given conversation.
|
||||
</Property>
|
||||
<Property name="limit" type="integer">
|
||||
Limit the number of attachments returned.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/attachments">
|
||||
|
||||
```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();
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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"
|
||||
// ...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Create an attachment {{ tag: 'POST', label: '/v1/attachments' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="file" type="string">
|
||||
The file you want to add as an attachment.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="POST" label="/v1/attachments">
|
||||
|
||||
```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,
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Retrieve an attachment {{ tag: 'GET', label: '/v1/attachments/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/attachments/Nc6yKKMpcxiiFxp6">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Update an attachment {{ tag: 'PUT', label: '/v1/attachments/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
This endpoint allows you to perform an update on an attachment. Currently, the only supported type of update is changing the filename.
|
||||
|
||||
### Optional attributes
|
||||
|
||||
<Properties>
|
||||
<Property name="filename" type="string">
|
||||
The new filename for the attachment.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="PUT" label="/v1/attachments/Nc6yKKMpcxiiFxp6">
|
||||
|
||||
```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',
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Delete an attachment {{ tag: 'DELETE', label: '/v1/attachments/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
This endpoint allows you to delete attachments. Note: This will permanently delete the file.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="DELETE" label="/v1/attachments/Nc6yKKMpcxiiFxp6">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
|
@ -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.
|
||||
|
||||
<div className="not-prose">
|
||||
<Button href="/sdks" variant="text" arrow="right">
|
||||
<>Check out our list of first-party SDKs</>
|
||||
</Button>
|
||||
</div>
|
||||
|
|
@ -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
|
||||
|
||||
<Properties>
|
||||
<Property name="id" type="string">
|
||||
Unique identifier for the contact.
|
||||
</Property>
|
||||
<Property name="username" type="string">
|
||||
The username for the contact.
|
||||
</Property>
|
||||
<Property name="phone_number" type="string">
|
||||
The phone number for the contact.
|
||||
</Property>
|
||||
<Property name="avatar_url" type="string">
|
||||
The avatar image URL for the contact.
|
||||
</Property>
|
||||
<Property name="display_name" type="string">
|
||||
The contact display name in the contact list. By default, this is just the
|
||||
username.
|
||||
</Property>
|
||||
<Property name="conversation_id" type="string">
|
||||
Unique identifier for the conversation associated with the contact.
|
||||
</Property>
|
||||
<Property name="last_active_at" type="timestamp">
|
||||
Timestamp of when the contact was last active on the platform.
|
||||
</Property>
|
||||
<Property name="created_at" type="timestamp">
|
||||
Timestamp of when the contact was created.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
---
|
||||
|
||||
## List all contacts {{ tag: 'GET', label: '/v1/contacts' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="limit" type="integer">
|
||||
Limit the number of contacts returned.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/contacts">
|
||||
|
||||
```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();
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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"
|
||||
// ...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Create a contact {{ tag: 'POST', label: '/v1/contacts' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="username" type="string">
|
||||
The username for the contact.
|
||||
</Property>
|
||||
<Property name="phone_number" type="string">
|
||||
The phone number for the contact.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
### Optional attributes
|
||||
|
||||
<Properties>
|
||||
<Property name="avatar_url" type="string">
|
||||
The avatar image URL for the contact.
|
||||
</Property>
|
||||
<Property name="display_name" type="string">
|
||||
The contact display name in the contact list. By default, this is just the username.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="POST" label="/v1/contacts">
|
||||
|
||||
```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',
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Retrieve a contact {{ tag: 'GET', label: '/v1/contacts/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/contacts/WAz8eIbvDR60rouK">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Update a contact {{ tag: 'PUT', label: '/v1/contacts/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="display_name" type="string">
|
||||
The contact display name in the contact list. By default, this is just the username.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="PUT" label="/v1/contacts/WAz8eIbvDR60rouK">
|
||||
|
||||
```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',
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Delete a contact {{ tag: 'DELETE', label: '/v1/contacts/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
This endpoint allows you to delete contacts from your contact list in Protocol. Note: This will also delete your conversation with the given contact.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="DELETE" label="/v1/contacts/WAz8eIbvDR60rouK">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
|
@ -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
|
||||
|
||||
<Properties>
|
||||
<Property name="id" type="string">
|
||||
Unique identifier for the conversation.
|
||||
</Property>
|
||||
<Property name="contact_id" type="string">
|
||||
Unique identifier for the other contact in the conversation.
|
||||
</Property>
|
||||
<Property name="group_id" type="string">
|
||||
Unique identifier for the group that the conversation belongs to.
|
||||
</Property>
|
||||
<Property name="pinned_message_id" type="string">
|
||||
Unique identifier for the pinned message.
|
||||
</Property>
|
||||
<Property name="is_pinned" type="boolean">
|
||||
Whether or not the conversation has been pinned.
|
||||
</Property>
|
||||
<Property name="is_muted" type="boolean">
|
||||
Whether or not the conversation has been muted.
|
||||
</Property>
|
||||
<Property name="last_active_at" type="timestamp">
|
||||
Timestamp of when the conversation was last active.
|
||||
</Property>
|
||||
<Property name="last_opened_at" type="timestamp">
|
||||
Timestamp of when the conversation was last opened by the authenticated
|
||||
user.
|
||||
</Property>
|
||||
<Property name="created_at" type="timestamp">
|
||||
Timestamp of when the conversation was created.
|
||||
</Property>
|
||||
<Property name="archived_at" type="timestamp">
|
||||
Timestamp of when the conversation was archived.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
---
|
||||
|
||||
## List all conversations {{ tag: 'GET', label: '/v1/conversations' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="limit" type="integer">
|
||||
Limit the number of conversations returned.
|
||||
</Property>
|
||||
<Property name="muted" type="boolean">
|
||||
Only show conversations that are muted when set to `true`.
|
||||
</Property>
|
||||
<Property name="archived" type="boolean">
|
||||
Only show conversations that are archived when set to `true`.
|
||||
</Property>
|
||||
<Property name="pinned" type="boolean">
|
||||
Only show conversations that are pinned when set to `true`.
|
||||
</Property>
|
||||
<Property name="group_id" type="string">
|
||||
Only show conversations for the specified group.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/conversations">
|
||||
|
||||
```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();
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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"
|
||||
// ...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Create a conversation {{ tag: 'POST', label: '/v1/conversations' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="contact_id" type="string">
|
||||
Unique identifier for the other contact in the conversation.
|
||||
</Property>
|
||||
<Property name="group_id" type="string">
|
||||
Unique identifier for the group that the conversation belongs to.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="POST" label="/v1/conversations">
|
||||
|
||||
```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',
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Retrieve a conversation {{ tag: 'GET', label: '/v1/conversations/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/conversations/xgQQXg3hrtjh7AvZ">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Update a conversation {{ tag: 'PUT', label: '/v1/conversations/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="pinned_message_id" type="string">
|
||||
Unique identifier for the pinned message.
|
||||
</Property>
|
||||
<Property name="is_pinned" type="boolean">
|
||||
Whether or not the conversation has been pinned.
|
||||
</Property>
|
||||
<Property name="is_muted" type="boolean">
|
||||
Whether or not the conversation has been muted.
|
||||
</Property>
|
||||
<Property name="archived_at" type="timestamp">
|
||||
Timestamp of when the conversation was archived.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="PUT" label="/v1/conversations/xgQQXg3hrtjh7AvZ">
|
||||
|
||||
```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,
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Delete a conversation {{ tag: 'DELETE', label: '/v1/conversations/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="DELETE" label="/v1/conversations/xgQQXg3hrtjh7AvZ">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
|
@ -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).
|
||||
|
||||
<Note>
|
||||
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.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
<Properties>
|
||||
<Property name="2xx">
|
||||
A 2xx status code indicates a successful response.
|
||||
</Property>
|
||||
<Property name="4xx">
|
||||
A 4xx status code indicates a client error — this means it's a _you_
|
||||
problem.
|
||||
</Property>
|
||||
<Property name="5xx">
|
||||
A 5xx status code indicates a server error — you won't be seeing these.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
---
|
||||
|
||||
## Error types
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
<Properties>
|
||||
<Property name="api_error">
|
||||
This means that we made an error, which is highly speculative and unlikely.
|
||||
</Property>
|
||||
<Property name="invalid_request">
|
||||
This means that you made an error, which is much more likely.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col>
|
||||
|
||||
```bash {{ title: "Error response" }}
|
||||
{
|
||||
"type": "api_error",
|
||||
"message": "No way this is happening!?",
|
||||
"documentation_url": "https://protocol.chat/docs/errors/api_error"
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
|
@ -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
|
||||
|
||||
<Properties>
|
||||
<Property name="id" type="string">
|
||||
Unique identifier for the group.
|
||||
</Property>
|
||||
<Property name="name" type="string">
|
||||
The name for the group.
|
||||
</Property>
|
||||
<Property name="description" type="string">
|
||||
The description for the group.
|
||||
</Property>
|
||||
<Property name="avatar_url" type="string">
|
||||
The avatar image URL for the group.
|
||||
</Property>
|
||||
<Property name="conversation_id" type="string">
|
||||
Unique identifier for the conversation that belongs to the group.
|
||||
</Property>
|
||||
<Property name="contacts" type="array">
|
||||
An array of contact objects that are members of the group.
|
||||
</Property>
|
||||
<Property name="created_at" type="timestamp">
|
||||
Timestamp of when the group was created.
|
||||
</Property>
|
||||
<Property name="archived_at" type="timestamp">
|
||||
Timestamp of when the group was archived.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
---
|
||||
|
||||
## List all groups {{ tag: 'GET', label: '/v1/groups' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="limit" type="integer">
|
||||
Limit the number of groups returned.
|
||||
</Property>
|
||||
<Property name="archived" type="boolean">
|
||||
Only show groups that are archived when set to `true`.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/groups">
|
||||
|
||||
```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();
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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"
|
||||
// ...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Create a group {{ tag: 'POST', label: '/v1/groups' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
This endpoint allows you to create a new group conversation between you and a group of your Protocol contacts.
|
||||
|
||||
### Required attributes
|
||||
|
||||
<Properties>
|
||||
<Property name="name" type="string">
|
||||
The name for the group.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
### Optional attributes
|
||||
|
||||
<Properties>
|
||||
<Property name="description" type="string">
|
||||
The description for the group.
|
||||
</Property>
|
||||
<Property name="avatar_url" type="string">
|
||||
The avatar image URL for the group.
|
||||
</Property>
|
||||
<Property name="contacts" type="array">
|
||||
An array of contact objects that are members of the group.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="POST" label="/v1/groups">
|
||||
|
||||
```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',
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```json {{ title: 'Response' }}
|
||||
{
|
||||
"id": "l7cGNIBKZiNJ6wqF",
|
||||
"name": "Plaza Hotel",
|
||||
"description": null,
|
||||
"avatar_url": null,
|
||||
"conversation_id": "ZYjVAbCE9g5XRlra",
|
||||
"contacts": [],
|
||||
"created_at": 692233200,
|
||||
"archived_at": null
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Retrieve a group {{ tag: 'GET', label: '/v1/groups/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/groups/L7cGNIBKZiNJ6wqF">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Update a group {{ tag: 'PUT', label: '/v1/groups/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="name" type="string">
|
||||
The new name for the group.
|
||||
</Property>
|
||||
<Property name="description" type="string">
|
||||
The new description for the group.
|
||||
</Property>
|
||||
<Property name="avatar_url" type="string">
|
||||
The new avatar image URL for the group.
|
||||
</Property>
|
||||
<Property name="contacts" type="array">
|
||||
An array of contact objects that are members of the group.
|
||||
</Property>
|
||||
<Property name="archived_at" type="timestamp">
|
||||
Timestamp of when the group was archived.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="PUT" label="/v1/groups/L7cGNIBKZiNJ6wqF">
|
||||
|
||||
```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.',
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
},
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Delete a group {{ tag: 'DELETE', label: '/v1/groups/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="DELETE" label="/v1/groups/L7cGNIBKZiNJ6wqF">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
|
@ -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' }}
|
||||
|
||||
<Note>
|
||||
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](#).
|
||||
</Note>
|
||||
|
||||
## 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.
|
||||
|
||||
<CodeGroup>
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
<div className="not-prose">
|
||||
<Button href="/sdks" variant="text" arrow="right">
|
||||
<>Check out our list of first-party SDKs</>
|
||||
</Button>
|
||||
</div>
|
||||
|
||||
## 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.
|
||||
|
||||
<CodeGroup tag="GET" label="/v1/conversations">
|
||||
|
||||
```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();
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
<div className="not-prose">
|
||||
<Button href="/conversations" variant="text" arrow="right">
|
||||
<>Read the docs for the Conversations endpoint</>
|
||||
</Button>
|
||||
</div>
|
||||
|
||||
## 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)
|
||||
|
|
@ -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
|
||||
|
||||
<Properties>
|
||||
<Property name="id" type="string">
|
||||
Unique identifier for the message.
|
||||
</Property>
|
||||
<Property name="conversation_id" type="string">
|
||||
Unique identifier for the conversation the message belongs to.
|
||||
</Property>
|
||||
<Property name="contact" type="object">
|
||||
The contact object for the contact who sent the message.
|
||||
</Property>
|
||||
<Property name="message" type="string">
|
||||
The message content.
|
||||
</Property>
|
||||
<Property name="reactions" type="array">
|
||||
An array of reaction objects associated with the message.
|
||||
</Property>
|
||||
<Property name="attachments" type="array">
|
||||
An array of attachment objects associated with the message.
|
||||
</Property>
|
||||
<Property name="read_at" type="timestamp">
|
||||
Timestamp of when the message was read.
|
||||
</Property>
|
||||
<Property name="created_at" type="timestamp">
|
||||
Timestamp of when the message was created.
|
||||
</Property>
|
||||
<Property name="updated_at" type="timestamp">
|
||||
Timestamp of when the message was last updated.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
---
|
||||
|
||||
## List all messages {{ tag: 'GET', label: '/v1/messages' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="conversation_id" type="string">
|
||||
Limit to messages from a given conversation.
|
||||
</Property>
|
||||
<Property name="limit" type="integer">
|
||||
Limit the number of messages returned.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/messages">
|
||||
|
||||
```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();
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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",
|
||||
// ..
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Send a message {{ tag: 'POST', label: '/v1/messages' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
This endpoint allows you to send a new message to one of your conversations.
|
||||
|
||||
### Required attributes
|
||||
|
||||
<Properties>
|
||||
<Property name="conversation_id" type="string">
|
||||
Unique identifier for the conversation the message belongs to.
|
||||
</Property>
|
||||
<Property name="message" type="string">
|
||||
The message content.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
### Optional attributes
|
||||
|
||||
<Properties>
|
||||
<Property name="attachments" type="array">
|
||||
An array of attachment objects associated with the message.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="POST" label="/v1/messages">
|
||||
|
||||
```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.’',
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Retrieve a message {{ tag: 'GET', label: '/v1/messages/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="GET" label="/v1/messages/SIuAFUNKdSYHZF2w">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Update a message {{ tag: 'PUT', label: '/v1/messages/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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
|
||||
|
||||
<Properties>
|
||||
<Property name="message" type="string">
|
||||
The message content.
|
||||
</Property>
|
||||
<Property name="reactions" type="array">
|
||||
An array of reaction objects associated with the message.
|
||||
</Property>
|
||||
<Property name="attachments" type="array">
|
||||
An array of attachment objects associated with the message.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="PUT" label="/v1/messages/SIuAFUNKdSYHZF2w">
|
||||
|
||||
```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'],
|
||||
],
|
||||
]);
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## Delete a message {{ tag: 'DELETE', label: '/v1/messages/:id' }}
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
This endpoint allows you to delete messages from your conversations. Note: This will permanently delete the message.
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
<CodeGroup title="Request" tag="DELETE" label="/v1/messages/SIuAFUNKdSYHZF2w">
|
||||
|
||||
```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');
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
|
@ -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
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
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.
|
||||
|
||||
<Properties>
|
||||
<Property name="starting_after" type="string">
|
||||
The last ID on the page you're currently on when you want to fetch the next page.
|
||||
</Property>
|
||||
<Property name="ending_before" type="string">
|
||||
The first ID on the page you're currently on when you want to fetch the previous page.
|
||||
</Property>
|
||||
<Property name="limit" type="integer">
|
||||
Limit the number of items returned.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col>
|
||||
|
||||
```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"
|
||||
// ...
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
|
@ -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`.
|
||||
|
||||
<div className="not-prose">
|
||||
<Button href="#event-types" variant="text" arrow="right">
|
||||
<>See all event types</>
|
||||
</Button>
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## Event types
|
||||
|
||||
<Row>
|
||||
<Col>
|
||||
|
||||
<Properties>
|
||||
<Property name="contact.created">
|
||||
A new contact was created.
|
||||
</Property>
|
||||
<Property name="contact.updated">
|
||||
An existing contact was updated.
|
||||
</Property>
|
||||
<Property name="contact.deleted">
|
||||
A contact was successfully deleted.
|
||||
</Property>
|
||||
<Property name="conversation.created">
|
||||
A new conversation was created.
|
||||
</Property>
|
||||
<Property name="conversation.updated">
|
||||
An existing conversation was updated.
|
||||
</Property>
|
||||
<Property name="conversation.deleted">
|
||||
A conversation was successfully deleted.
|
||||
</Property>
|
||||
<Property name="message.created">
|
||||
A new message was created.
|
||||
</Property>
|
||||
<Property name="message.updated">
|
||||
An existing message was updated.
|
||||
</Property>
|
||||
<Property name="message.deleted">
|
||||
A message was successfully deleted.
|
||||
</Property>
|
||||
<Property name="group.created">
|
||||
A new group was created.
|
||||
</Property>
|
||||
<Property name="group.updated">
|
||||
An existing group was updated.
|
||||
</Property>
|
||||
<Property name="group.deleted">
|
||||
A group was successfully deleted.
|
||||
</Property>
|
||||
<Property name="attachment.created">
|
||||
A new attachment was created.
|
||||
</Property>
|
||||
<Property name="attachment.updated">
|
||||
An existing attachment was updated.
|
||||
</Property>
|
||||
<Property name="attachment.deleted">
|
||||
An attachment was successfully deleted.
|
||||
</Property>
|
||||
</Properties>
|
||||
|
||||
</Col>
|
||||
<Col sticky>
|
||||
|
||||
```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
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</Col>
|
||||
</Row>
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
<CodeGroup title="Verifying a request">
|
||||
|
||||
```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
|
||||
}
|
||||
```
|
||||
|
||||
</CodeGroup>
|
||||
|
||||
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!
|
||||
|
|
@ -61,7 +61,7 @@ function Anchor({
|
|||
>
|
||||
{inView && (
|
||||
<div className="absolute ml-[calc(-1*var(--width))] mt-1 hidden w-[var(--width)] opacity-0 transition [--width:calc(2.625rem+0.5px+50%-min(50%,calc(theme(maxWidth.lg)+theme(spacing.8))))] group-hover:opacity-100 group-focus:opacity-100 md:block lg:z-50 2xl:[--width:theme(spacing.10)]">
|
||||
<div className="group/anchor block h-5 w-5 rounded-lg bg-zinc-50 ring-1 ring-inset ring-zinc-300 transition hover:ring-zinc-500 dark:bg-zinc-800 dark:ring-zinc-700 dark:hover:bg-zinc-700 dark:hover:ring-zinc-600">
|
||||
<div className="group/anchor block h-5 w-5 rounded bg-zinc-50 ring-1 ring-inset ring-zinc-300 transition hover:ring-zinc-500 dark:bg-zinc-800 dark:ring-zinc-700 dark:hover:bg-zinc-700 dark:hover:ring-zinc-600">
|
||||
<AnchorIcon className="h-5 w-5 stroke-zinc-500 transition dark:stroke-zinc-400 dark:group-hover/anchor:stroke-white" />
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
Loading…
Reference in a new issue