Get SMS engagement details for a contact.

To get a contact’s SMS engagement details, such as SMS consent and advertising frequency, make a GET call to the /contacts/sms_engagement_history/{contact_id} endpoint.

The following shows example SMS engagement details that display in the response.

[
  {
    "contact_id": "60ff35c6-3520-11ed-8a01-fa163e595591",
    "sms_channel_id": "614dc77c-3520-11ed-8a01-fa163e595591",
    "sms_channel_history_id": "614de3b0-3520-11ed-8a01-fa163e595591",
    "insert_time": "2022-09-15T14:01:10-04:00",
    "history_details": {
      "state": "E",
      "source": "A",
      "consent_type": "promotional_sms",
      "source_sms_number": "6035550239",
      "consent_action_time": "2021-07-18 00:00:00 -0400",
      "consent_action_type": "opt_in",
      "consent_medium_type": "FI",
      "source_consent_timestamp": "2021-07-18"
    }
  }
]

Properties

The properties returned depend on the type of SMS consent granted by the contact.

  • contact_id: The UUID that uniquely identifies a contact.
  • sms_channel_id: The UUID that uniquely identifies an SMS channel.
  • sms_channel_history_id: The UUID that uniquely identifies the SMS channel history.
  • insert_time: The date and time that the history record was created, in ISO-8601 format. System generated.
  • history_details:
    • state: The code representing the consent state, including E for optin and O for Optin.
    • source: The code representing the consent source type, including A for Account, C for Contact, and S’ for System.
    • consent_type: The type of SMS consent used, promotional_sms or transactional_sms.
    • consent_action_time: The date and time that the engagement data was last updated, in ISO-8601 format. System generated.
    • consent_action_type: The type of consent action provided, including:
      • opt_out
      • re_opt_in
      • delete
      • confirmed_opt_in
      • deactivate”`
      • suspend
      • resubscribe
    • consent_medium_type: The code representing the medium used to provide consent. Types include:
      • mobile device (MD)
      • lead generation form(LF)
      • deactivation by carrier(CD)
      • import_file:(FI)
      • system (SY).
    • consent_medium_url: If applicable, the URL used to provide consent.
    • consent_medium_details: If applicable, additional information for the consent.
    • source_sms_number: If applicable, the SMS consent number associated with the source.
    • source_consent_timestamp: The time that SMS consent was last updated.
    • advertised_frequency: If applicable, the advertising numeric component used to advertise to the contact.. For example, if advertised_frequency is set to 2 , and advertised_interval is set to M, the contact receives advertisements twice a month.
    • advertised_interval: If applicable, the interval component used to advertise to the contact. For example, if advertised_frequency is set to 2 , and advertised_interval is set to M, the contact receives advertisements twice a month. Options include:
      • Month (M)
      • Day (D)
      • Week (W)

Example Request

GET https://api.cc.email/v3/contacts/sms_engagement_history/{contact_id}

Endpoint Requirements

User privileges: contacts:read

Authorization scopes: contact_data

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.cc.email/v3/contacts/sms_engagement_history/60ff35c6-3520-11ed-8a01-fa163e595999',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Accept: */*',
    'Content-Type: application/json',
    'Authorization: Bearer {access_token}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

curl --location 'https://api.cc.email/v3/contacts/sms_engagement_history/60ff35c6-3520-11ed-8a01-fa163e595999' \
--header 'Accept: */*' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}'
OkHttpClient client = new OkHttpClient().newBuilder()
        .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, "");
        Request request = new Request.Builder()
        .url("https://api.cc.email/v3/contacts/sms_engagement_history/60ff35c6-3520-11ed-8a01-fa163e595999")
        .method("GET", body)
        .addHeader("Accept", "*/*")
        .addHeader("Content-Type", "application/json")
        .addHeader("Bearer {access_token}")
        .build();
        Response response = client.newCall(request).execute();

Example Response Body

[
  {
    "contact_id": "60ff35c6-3520-11ed-8a01-fa163e595591",
    "sms_channel_id": "614dc77c-3520-11ed-8a01-fa163e595591",
    "sms_channel_history_id": "614de3b0-3520-11ed-8a01-fa163e595591",
    "insert_time": "2022-09-15T14:01:10-04:00",
    "history_details": {
      "state": "E",
      "source": "A",
      "consent_type": "promotional_sms",
      "source_sms_number": "6035550239",
      "consent_action_time": "2021-07-18 00:00:00 -0400",
      "consent_action_type": "opt_in",
      "consent_medium_type": "FI",
      "source_consent_timestamp": "2021-07-18"
    }
  }
]

Try it!