Contact Communications

Contact Communications are automated messages that are scheduled to be sent to a contact as a part of a campaign.
They are created automatically after a contact is added to a campaign (by creating a new campaign contact )

Update a contact communication
Find all contact communications
Filtering contact communications

The following fields relate to the Contact Communications endpoint.

Email ContactCall ContactText Contact

Field	Required?	Writeable?
campaign_name	No	No
The name of the campaign that the contact communication is a part of
type	No	No
The type of contact communciation Possible values:
is_stopped_on_text_reply	No	No
Stop contact communication if the contact responds to the outgoing text message. Only relevant if type = Text Contact
template_subject	No	No
The subject of the contact communication template.
template_name	No	No
The name of the template being used for emailing or texting a contact
template_folder_name	No	No
The folder the contact communication template is stored in
is_active	Yes	Yes
A boolean value to depict whether or not a contact communication has been dispatched or completed. Equals to true if not yet dispatched, otherwise it equals to false.
send_at	No	No
The date and time at which a contact communication is scheduled to be dispatched.
completed_at	No	No
The date and time at which a contact communication was dispatched. Is equal to null if the contact communication has not been sent yet
send_from_user_id	No	No
The agent that the contact communication will be displayed as being sent from
completing_user_id	No	No
The ID of the user who marked the contact communication as complete. Is equal to null if is_acitve = false

Update one Contact Communication

The following users can mark a contact communication as active or inactive:

The contact's owner
The contact owner's team member
The contact's assigned user
Any user the contact has been shared with

When the value of is_active changes, Contact Communication, the following fields are automatically updated:

is_active = false (the contact communication is completed)
- completing_user_id is set to the ID of the user that marked it as completed
- completed_at is set to the date and time at which the contact communication was sent or was marked as completed
is_active = true (the contact communication is incomplete)
- completing_user_id is set to null
- completed_at is set to null

To update some attributes on one contact communication:

PATCH https://api-v2.liondesk.com//contacts/76/campaign-communications/10

headers: {
  Authorization: "Bearer [access token]",
  Content-Type: "application/json"
}
data: {  template_name: "Text Template",
  is_active: "true"
}

Find All Contact Communications

You find/search contact communications by issuing a GET request to the base endpoint:

GET https://api-v2.liondesk.com//contacts/76/campaign-communications

headers: {
  Authorization: "Bearer [access token]",
  Content-Type: "application/json"
}

The response will contain an array of contact communication objects, like so:

{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "campaign_name": "New Contact Campaign",
      "type": "Text Contact",
      "is_stopped_on_text_reply": true,
      "template_subject": "Import Deadline",
      "template_name": "Text Template",
      "template_folder_name": "New Contacts Template Folder",
      "is_active": true,
      "send_at": "2028-09-12T18:31:35.000Z",
      "completed_at": null,
      "send_from_user_id": 3,
      "completing_user_id": 76
    },
    {
      "campaign_name": "Old Contact Campaign",
      "type": "Email Contact",
      "is_stopped_on_text_reply": false,
      "template_subject": "Saying Hello",
      "template_name": "Email Template",
      "template_folder_name": "Old Contacts Template Folder",
      "is_active": false,
      "send_at": "2017-12-06T22:11:02.000Z",
      "completed_at": "2017-12-06T22:11:02.000Z",
      "send_from_user_id": 4,
      "completing_user_id": null
    }
  ]
}

Loading additional information

Information associated with send_from_user and completing_user can be returned by appending the $load parameter to any GET request:

GET https://api-v2.liondesk.com//contacts/76/campaign-communications?$load=send_from_user,completing_user

headers: {
  Authorization: "Bearer [access token]",
  Content-Type: "application/json"
}

{
  "total": 2,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "campaign_name": "New Contact Campaign",
      "type": "Text Contact",
      "is_stopped_on_text_reply": true,
      "template_subject": "Import Deadline",
      "template_name": "Text Template",
      "template_folder_name": "New Contacts Template Folder",
      "is_active": true,
      "send_at": "2028-09-12T18:31:35.000Z",
      "completed_at": null,
      "send_from_user_id": 3,
      "completing_user_id": 76,
      "send_from_user": {
        "id": 99,
        "first_name": "Ana",
        "last_name": "Amari"
      },
      "completing_user": {
        "id": 76,
        "first_name": "Jack",
        "last_name": "Morrison"
      }
    },
    {
      "campaign_name": "Old Contact Campaign",
      "type": "Email Contact",
      "is_stopped_on_text_reply": false,
      "template_subject": "Saying Hello",
      "template_name": "Email Template",
      "template_folder_name": "Old Contacts Template Folder",
      "is_active": false,
      "send_at": "2017-12-06T22:11:02.000Z",
      "completed_at": "2017-12-06T22:11:02.000Z",
      "send_from_user_id": 4,
      "completing_user_id": null,
      "send_from_user": {
        "id": 44,
        "first_name": "Gabriel",
        "last_name": "Reyes"
      },
      "completing_user": null
    }
  ]
}

Filtering Contact Communications

The following filtering operators may be mixed and matched as desired.

Equality

You may query contact communication fields directly by specifying equality parameters in the request URI:GET /contacts/76/campaign-communications?template_name=undefined

You may wish to exclude results having some value with $ne:GET /contacts/76/campaign-communications?is_active[$ne]=undefined

Dates & Times

Unless otherwise stated all dates and times should be in ISO8601 format. Examples: 2012-09-27, 2012-09-27T09:15:00Z (UTC), 2012-09-27T09:15:00-07:00 (PDT)

Limiting and Pagination

$limit will return only the number of results you specify: GET /contacts/76/campaign-communications?$limit=2

$skip will skip the specified number of results, useful for paginating:GET /contacts/76/campaign-communications?is_active=undefined&$limit=2&$skip=2

Sorting

$sort will order results based on the field given.

Use 1 for ascending order, and -1 for descending order:GET /contacts/76/campaign-communications?$limit=10&$sort[send_at]=-1

Inclusion / Exclusion

Find all records where the property values are ($in) some set:GET /contacts/76/campaign-communications?type[$in]=undefinedIf the column matches any of the given values, the resource shall be returned.

Similarly, you may exclude certain values with ($nin):GET /contacts/76/campaign-communications?type[$nin]=undefined

Comparisons

You may use the less-than $lt and less-than-or-equal $lte operators to filter your queries: GET /contacts/76/campaign-communications?send_at[$lt]=2020-01-01T00:00:00Z

Similarly, you may use greater-than $gt and greater-than-or-equal $gte operators to filter your queries: GET /contacts/76/campaign-communications?send_at[$gte]=2018-05-07T10:00:00Z

You may also combine these operators to query for a range of values: GET /contacts/76/campaign-communications?send_at[$gte]=2019-01-01T11:00:00Z&send_at[$lte]=2019-01-31T00:00:00Z

Partial String Matching

Find all records where the property values includes the value you are searching for ($like):

GET /contacts/76/campaign-communications?campaign_name[$like]=%New%

It may be necessary to escape the percent sign (%) characters to ensure proper encoding:

GET /contacts/76/campaign-communications?campaign_name[$like]=%25New%25