Customers

Customers are an essential part of Cari Finance — they are the containers for the transactions between you and your contacts. 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 the customers between you and your contacts. In addition, customers can also be group-based with more than one contact, they can have a pinned message, and they can be muted.

Properties

Name
id
Type
string
Description
Unique identifier for the customer.
Name
contact_id
Type
string
Description
Unique identifier for the other contact in the customer.
Name
group_id
Type
string
Description
Unique identifier for the group that the customer belongs to.
Name
pinned_message_id
Type
string
Description
Unique identifier for the pinned message.
Name
is_pinned
Type
boolean
Description
Whether or not the customer has been pinned.
Name
is_muted
Type
boolean
Description
Whether or not the customer has been muted.
Name
last_active_at
Type
timestamp
Description
Timestamp of when the customer was last active.
Name
last_opened_at
Type
timestamp
Description
Timestamp of when the customer was last opened by the authenticated user.
Name
created_at
Type
timestamp
Description
Timestamp of when the customer was created.
Name
archived_at
Type
timestamp
Description
Timestamp of when the customer was archived.

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.
Name
muted
Type
boolean
Description
Only show customers that are muted when set to true.
Name
archived
Type
boolean
Description
Only show customers that are archived when set to true.
Name
pinned
Type
boolean
Description
Only show customers that are pinned when set to true.
Name
group_id
Type
string
Description
Only show customers for the specified group.

Request

GET

/v1/customers

curl -G https://api.cari.finance/customers \
  -H "Authorization: Bearer {token}" \
  -d limit=10

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

POST/v1/conversations

Create a conversation

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

Name
contact_id
Type
string
Description
Unique identifier for the other contact in the conversation.
Name
group_id
Type
string
Description
Unique identifier for the group that the conversation belongs to.

Request

POST

/v1/conversations

curl https://api.protocol.chat/v1/conversations \
  -H "Authorization: Bearer {token}" \
  -d 'contact_id'="WAz8eIbvDR60rouK"

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
}

GET/v1/conversations/:id

Retrieve a conversation

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

Request

GET

/v1/conversations/xgQQXg3hrtjh7AvZ

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

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
}

PUT/v1/conversations/:id

Update a conversation

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

Name
pinned_message_id
Type
string
Description
Unique identifier for the pinned message.
Name
is_pinned
Type
boolean
Description
Whether or not the conversation has been pinned.
Name
is_muted
Type
boolean
Description
Whether or not the conversation has been muted.
Name
archived_at
Type
timestamp
Description
Timestamp of when the conversation was archived.

Request

PUT

/v1/conversations/xgQQXg3hrtjh7AvZ

curl -X PUT https://api.protocol.chat/v1/conversations/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'is_muted'=true

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

Delete a conversation

This endpoint allows you to delete your conversations in Cari Finance. Note: This will permanently delete the conversation and all its messages — archive it instead if you want to be able to restore it later.

Request

DELETE

/v1/conversations/xgQQXg3hrtjh7AvZ

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