Contacts

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

Properties

Name
id
Type
string
Description
Unique identifier for the contact.
Name
name
Type
string
Description
The contact display name in the contact list. By default, this is just the username.
Name
address
Type
string
Description
Address of the contact.
Name
channel
Type
string
Description
The channel where received the contact. Example: phone, email, viber, etc.
Name
notes
Type
string
Description
The contact's note that saved by agent.
Name
company
Type
object
Description
Associated company with this contact.
Name
custom_fields
Type
array of objects
Description
Key value pair containing the name and value of the custom fields.
Name
tags
Type
array of objects
Description
Associated tags with this contact.
Name
phone
Type
array of objects
Description
Additional phones associated with the contact.
Name
email
Type
array of objects
Description
Additional emails associated with the contact.
Name
contact_groups
Type
array of objects
Description
Additional groups associated with the contact.

GET/api/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

Name
keyword
Type
string
Description
Search the contacts by keywords. You cannot search with a substring. For example, a contact "Kyaw Kyaw" can be looked up using "kyaw", "Kya", "yaw" and "aw".

Request

GET

/api/v1/contacts

curl -G https://api.klink.cloud/api/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -d keyword={your_keyword_here}

Response

{
  "total": 65,
  "page": 1,
  "pageSize": 10,
  "lastPage": 7,
  "data": [
    {
        "id": "eefdaf75-ed19-4291-8e47-913f1205d02d",
        "name": "Aria ",
        "address": "Dagon Seikkan Township",
        "channel": "phone",
        "notes": null,
        "avatar_url": null,
        "tags": [
          {
            "id": "258fc2c9-738d-4889-806c-0955a3b892c3",
            "name": "platinum"
          }
        ],
        "company": {
            "id": "5073bd60-dee4-4866-a798-42c37300171c",
            "name": "Cool Entreprise",
            "phone": null,
            "address": null,
            "industry": null
        },
        "email": [
            {
                "email": "mistercustomer@gmail.com"
                "is_primary": false
            }
        ],
        "phone": [
            {
                "phone": "09797877765"
                "is_primary": true
            }
        ],
        "custom_fields": [
            {
                "system_name": "cf_sector"
                "display_name": "sector`"
                "type": "text"
                "value": "Finance"
            }
        ],
        "contact_groups": [
          {
            "id": "7b03581e-78d1-47fa-aaf0-8f5b3733a803",
            "name": "Myanmar"
          }
        ]
    },
    {
      "id": "eefdaf75-434ew-6565-8e47-345vrt34534v"
      // ...
    }
  ]
}

POST/api/v1/contacts

Create a contact

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

Required attributes

Name
username
Type
string
Description
The username for the contact.
Name
email
Type
array of objects
Description
An array of objects which has email and is_primary as keys. (can be provided as empty array)
Name
phone
Type
array of objects
Description
An array of objects which has phone and is_primary as keys. (can be provided as empty array)

Optional attributes

Name
avatar_url
Type
string
Description
The avatar image URL for the contact.
Name
company
Type
string
Description
Name of the company associated with the contact.
Name
tags
Type
array
Description
Associated tags with this contact. (an array of tags'names and will create new tag if not exists)
Name
channel
Type
string
Description
The channel where received the contact. Example: phone, email, viber, etc. (accept only name of the channel you have in app).
Name
address
Type
string
Description
Address of the contact.
Name
notes
Type
string
Description
The contact's note that saved by agent.
Name
contact_groups
Type
array
Description
An array of contact group ids.
Name
custom_fields
Type
object
Description
A key value pair object with name of custom field as key.

Request

POST

/api/v1/contacts

curl https://api.klink.cloud/api/v1/contacts \
  -H "Authorization: Bearer {token}" \
  -d name="FrankMcCallister" \
  -d email = [] \
  -d phone=[{"phone": "1-800-759-3000", "is_primary": true }] \
  -d avatar_url="https://assets.protocol.chat/avatars/frank.jpg"

Response

{
  "name": "FrankMcCallister4",
  "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
  "company": null,
  "id": "b10e10c4-1971-4ed4-ae88-ea571d786b9b",
  "email": [],
  "phone": [
    {
      "phone": "1-800-759-3000",
      "is_primary": true
    }
  ]
}

GET/api/v1/contacts/:id

Retrieve a contact

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

Request

GET

/api/v1/contacts/c786bb40-a58e-4d60-afe6-061e2b918811

curl https://api.klink.cloud/api/v1/contacts/c786bb40-a58e-4d60-afe6-061e2b918811 \
-H "Authorization: Bearer {token}"

Response


"status": "success",
"message": "contact",
"data": {
    "id": "c786bb40-a58e-4d60-afe6-061e2b819811",
    "name": "FrankMcCallister",
    "address": null,
    "channel": null,
    "notes": null,
    "avatar_url": "https://assets.protocol.chat/avatars/frank.jpg",
    "tags": [
      {
          "id": "4d45ba6c-728e-4ca8-91cb-91bac1572622",
          "name": "platinum"
      }
    ],
    "company": {
      "id": "547f2af6-1e6d-420e-aaed-b6448d37fd08",
      "name": "K-Link",
      "phone": null,
      "address": null,
      "industry": null
    },
    "email": [
      {
          "email": "frankmccallister@gmail.com",
          "is_primary": true
      }
    ],
    "phone": [
      {
          "phone": "1-800-759-3000",
          "is_primary": true
      }
    ],
    "custom_fields": [
      {
          "system_name": "demo_test",
          "display_name": "demo test ddddfee erefesf",
          "type": "text",
          "value": "another field"
      }
    ],
    "contact_groups": [
      {
          "id": "7b03581e-78d1-47fa-aaf0-8f5b3733a803",
          "name": "new"
      }
    ]
}

PUT/api/v1/contacts/:id

Update a contact

This endpoint allows you to perform an update on a contact.

Required attributes

Name
specific_update_fields
Type
array
Description
Only fields which are explicitly defined in this specific_update_fields will be updated. (If name and email fields are provided in request body but only name is in specific_update_fields, only name will be updated.)

***Provide empty array to update all fields you have included in request body.

Optional attributes

Other attributes provided in Contact model.

Request

PUT

/api/v1/contacts/WAz8eIbvDR60rouK

curl -X PUT https://api.klink.cloud/api/v1/contacts/WAz8eIbvDR60rouK \
  -H "Authorization: Bearer {token}" \
  -d name="UncleFrank" \
  -d specific_update_fields=[]

Response

{
  "status": "success",
  "message": "updating contact",
  "data": null
}

DELETE/api/v1/contacts/:id

Delete a contact

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

Request

DELETE

api/v1/contacts/WAz8eIbvDR60rouK

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

Response

{
  "status": "success",
  "message": "deleting contact",
  "data": null
}

Get/api/v1/contacts/groups

Get Contact Groups

This endpoint allows you to get contact groups. You can use this endpoint to get ids of contact groups to include in create contact endpoint.

Request

GET

/v1/contacts/groups

curl -X GET https://api.klink.cloud/api/v1/contacts/groups \
  -H "Authorization: Bearer {token}"

Response

{
  "total": 49,
  "page": 1,
  "pageSize": 10,
  "lastPage": 5,
  "data": [
    {
      "id": "7b03581e-78d1-47fa-aaf0-8f5b3733a803",
      "value": "new",
      "label": "new",
      "is_default": false
    },
    .....
  ]
}

Get/api/v1/contacts/fields

Get Contact Fields

This endpoint allows you to get available contact fields including the custom fields you have created.

Request

GET

/v1/contacts/fields

curl -X GET https://api.klink.cloud/api/v1/contacts/fields \
  -H "Authorization: Bearer {token}"

Response

{
  "total": 49,
  "page": 1,
  "pageSize": 10,
  "lastPage": 5,
  "data": [
    {
      "id": "464b7eef-22ed-435e-9bef-35b58e435eda",
      "system_name": "channel",
      "display_name": "Channel",
      "type": "select",
      "is_default": true,
      "is_archived": true,
      "is_required": true,
      "is_unique": false,
      "options": [
          {
              "value": "phone",
              "label": "Phone",
              "is_default": true
          },
          {
              "value": "G-Mail",
              "label": "G-Mail",
              "is_default": false
          },
        ]
    },
    .....
  ]
}