Customers

As the name suggests, customers are a core part of Protocol — the very reason Protocol exists is so you can have secure conversations with your customers. On this page, we'll dive into the different customer endpoints you can use to manage customers programmatically. We'll look at how to query, create, update, and delete customers.

The customer model

The customer model contains all the information about your customers, such as their username, avatar, and phone number. It also contains a reference to the conversation between you and the customer and information about when they were last active on Protocol.

Properties

Name
id
Type
string
Description
Unique identifier for the customer.
Name
project_id
Type
string
Description
Identifier for the project associated with the customer.
Name
external_id
Type
string
Description
External identifier for the customer.
Name
last_transaction_at
Type
timestamp
Nullable
NULLABLE
Description
Timestamp of the last transaction made by the customer, if any.
Name
status
Type
string
Description
The current status of the customer (e.g., "active").
Name
terminated_at
Type
timestamp
Nullable
NULLABLE
Description
Timestamp of when the customer's account was terminated, if applicable.
Name
is_flagged
Type
boolean
Description
Indicates whether the customer is flagged for any particular reason.

Name: identity
Type: object
Description: Identity of the customer

Name
updated_at
Type
timestamp
Description
Timestamp of when the customer's information was last updated.
Name
meta
Type
object
Description
A metadata object associated with the customer.
Name
created_at
Type
timestamp
Description
Timestamp of when the customer account was created.

GET/v1/customers

List all customers

This endpoint allows you to retrieve a paginated list of all your customers. By default, a maximum of ten customers are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of customers returned.

Request

GET

/v1/customers

curl -G https://api.protocol.chat/v1/customers \
  -H "Authorization: Bearer {token}" \
  -d active=true \
  -d limit=10

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"
      // ...
    }
  ]
}

POST/v1/customers

Create a customer

This endpoint allows you to add a new customer to your customer list in Protocol. To add a customer, you must provide their Protocol username and phone number.

Required attributes

Name
username
Type
string
Description
The username for the customer.
Name
phone_number
Type
string
Description
The phone number for the customer.

Optional attributes

Name
avatar_url
Type
string
Description
The avatar image URL for the customer.
Name
display_name
Type
string
Description
The customer display name in the customer list. By default, this is just the username.

Request

POST

/v1/customers

curl https://api.protocol.chat/v1/customers \
  -H "Authorization: Bearer {token}" \
  -d username="FrankMcCallister" \
  -d phone_number="1-800-759-3000" \
  -d avatar_url="https://assets.protocol.chat/avatars/frank.jpg"

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
}

GET/v1/customers/:id

Retrieve a customer

This endpoint allows you to retrieve a customer by providing their Protocol id. Refer to the list at the top of this page to see which properties are included with customer objects.

Request

GET

/v1/customers/WAz8eIbvDR60rouK

curl https://api.protocol.chat/v1/customers/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}"

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
}

PATCH/v1/customers/:id

Update a customer

This endpoint allows you to perform an update on a customer. Currently, the only attribute that can be updated on customers is the display_name attribute which controls how a customer appears in your customer list in Protocol.

Optional attributes

Name
display_name
Type
string
Description
The customer display name in the customer list. By default, this is just the username.

Request

PATCH

/v1/customers/WAz8eIbvDR60rouK

curl -X PATCH https://api.protocol.chat/v1/customers/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d display_name="UncleFrank"

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/v1/customers/:id

Delete a customer

This endpoint allows you to delete customers from your customer list in Protocol. Note: This will also delete your conversation with the given customer.

Request

DELETE

/v1/customers/WAz8eIbvDR60rouK

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