Opt-in & Opt-out

Registering Opt-in & Opt-out requests

Introduction to Opt-in & Opt-out

By using the Opt-in & Opt-out service, it's possible to register an opt-in or an opt-out event for a contact with the underlying channel. In order to execute the request, either the contactId of the contact or its channel recipient identities are required.

In the Beta version of the Conversation API, the Opt-in & Opt-out registration is only supported for WhatsApp channel. To read more about relevant policies go to WhatsApp Opt-in and Opt-out.

Requests are executed asynchronously, therefore the endpoint immediately returns the registered request. The result of the Opt-in or Opt-out request is posted to the webhook which has an OPTIN or OPTOUT trigger respectively. To read more about setting up webhooks go to Webhooks.

Opt-in

Opt-in Request

Below you can find an example to register an Opt-in event.

Conversation API POST optins:register

{
  "app_id": "{{APP_ID}}",
  "channels": ["WHATSAPP"],
  "recipient": {
    "contact_id": "{{CONTACT_ID}}"
  }
}

Alternatively the contact's channel recipient identities can be used:

{
  "app_id": "{{APP_ID}}",
  "channels": ["WHATSAPP"],
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "WHATSAPP",
          "identity": "14707864783"
        }
      ]
    }
  }
}

Opt-in Response

The response for Opt-in is the registered request. The result is returned through the webhook with OPT_IN trigger, see Opt-In Notification.

Opt-in Notification

The result of registering an Opt-in is posted to the webhook which has OPT_IN trigger set.

Below you can find an example for Opt-in Notification.

{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2021-06-08T07:54:03.165316Z",
  "event_time": "2021-06-08T07:54:02.112Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "opt_out_notification": {
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "channel": "WHATSAPP",
    "identity": "46712312312",
    "status": "OPT_IN_SUCCEEDED",
    "request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
  }
}

The Opt-in Notification can have the following fields:

Field Description
contact_id The id of the contact that the Opt-in was executed for.
identity The channel recipient identity of the contact.
channel The channel that the Opt-in was registered with.
status The status response for the Opt-in request. See possible values below the table.
error_details If the Opt-in failed the reason is present in this field.

Possible values for status are:

  • OPT_IN_STATUS_UNSPECIFIED : the underlying channel doesn't support Opt-in.
  • OPT_IN_SUCCEEDED : the Opt-in registration succeeded.
  • OPT_IN_FAILED : the Opt-in registration failed, see reason in error_details field.

Opt-out

Opt-out Request

Below you can find an example to register an Opt-out event.

Conversation API POST optouts:register

{
  "app_id": "01EB37HMH1M6SV18ASNS3G135H",
  "accepted_time": "2021-06-08T07:54:03.165316Z",
  "event_time": "2021-06-08T07:54:02.112Z",
  "project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
  "opt_out_notification": {
    "contact_id": "01EKA07N79THJ20WSN6AS30TMW",
    "channel": "WHATSAPP",
    "identity": "46712312312",
    "status": "OPT_OUT_SUCCEEDED",
    "request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
  }
}

Alternatively the contact's channel recipient identities can be used:

{
  "app_id": "{{APP_ID}}",
  "channels": ["WHATSAPP"],
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "WHATSAPP",
          "identity": "14707864783"
        }
      ]
    }
  }
}

Opt-out Response

The response for Opt-out is the registered request. The result is returned through the webhook which has OPT_OUT trigger, see Opt-Out Notification.

Opt-out Notification

The result of registering an Opt-out is posted to the webhook which has OPT_OUT trigger set.

Below you can find an example for Opt-out Notification.

{
  "contact_id": "{{CONTACT_ID}}",
  "channel": "WHATSAPP",
  "identity": "46712312312",
  "status": "OPT_OUT_SUCCEEDED"
}

The Opt-out notification can have the following fields:

Field Description
contact_id The id of the contact that the Opt-out was executed for.
identity The channel recipient identity of the contact.
channel The channel that the Opt-out was registered with.
status The status response for the Opt-out request. see below for possible values
error_details If the Opt-out failed the reason is present in this field.

Possible values for status are:

  • OPT_OUT_STATUS_UNSPECIFIED : the underlying channel doesn't support Opt-out.
  • OPT_OUT_SUCCEEDED : the Opt-out registration succeeded.
  • OPT_OUT_FAILED : the Opt-out registration failed, see reason in error_details