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
    customFields
    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.


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"
                "isPrimary": false
            }
        ],
        "phone": [
            {
                "phone": "09797877765"
                "isPrimary": true
            }
        ],
        "customFields": [
            {
                "system_name": "cf_sector"
                "display_name": "sector`"
                "type": "text"
                "value": "Finance"
            }
        ]
    },
    {
      "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 isPrimary as keys. (can be provided as empty array)

  • Name
    phone
    Type
    array of objects
    Description

    An array of objects which has phone and isPrimary 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
    customFields
    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", "isPrimary": 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",
      "isPrimary": 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",
          "isPrimary": true
      }
    ],
    "phone": [
      {
          "phone": "1-800-759-3000",
          "isPrimary": true
      }
    ],
    "customFields": [
      {
          "system_name": "demo_test",
          "display_name": "demo test ddddfee erefesf",
          "type": "text",
          "value": "another field"
      }
    ],
}

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
          },
        ]
    },
    .....
  ]
}