Contacts

As the name suggests, contacts are a core part of CityPay — the very reason CityPay 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.

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

    Attributes

GET/v1/contacts

List all 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

    Attributes

Request

GET
/v1/contacts
curl -G https://api.protocol.chat/v1/contacts \
  -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/contacts

Create a contact

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

Required attributes

    Attributes

Optional attributes

    Attributes

Request

POST
/v1/contacts
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"

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/contacts/:id

Retrieve a contact

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

Request

GET
/v1/contacts/WAz8eIbvDR60rouK
curl https://api.protocol.chat/v1/contacts/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
}
PUT/v1/contacts/:id

Update a contact

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

    Attributes

Request

PUT
/v1/contacts/WAz8eIbvDR60rouK
curl -X PUT https://api.protocol.chat/v1/contacts/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/contacts/:id

Delete a contact

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

Request

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