Download OpenAPI specification:Download

OptIn & OptOut

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.

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 OPT_IN or OPT_OUT trigger respectively. To read more about setting up webhooks go to Webhooks.

Register an opt-in

This method is asynchronous - it returns immediately the requested OptIn registration with any defaults resolved. All changes of the actual opt-in status are then delivered as callbacks to registered webhooks with trigger OPT_IN.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

query Parameters
request_id
string

ID for the asynchronous request, will be generated if not set. Currently this field is not used for idempotency but it will be added in v1.

Request Body schema: application/json

The opt-in request.

app_id
required
string

The app for which the Opt-In is being registered.

channels
required
Array of strings (Channel Identifier)

The channels covered by this Opt-In. The default are all the channels for a contact if recipient is contact_id or the channels in the channel_identities list.

Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "LINE" "WECHAT"
required
contact_id (object) or identified_by (object)

The recipient to opt-in. Requires either contact_id or identified_by. If Dispatch Mode is used, only identified_by is allowed.

processing_strategy
string (ProcessingStrategy)

Overrides the app's Processing Mode. Default value is DEFAULT.

Enum: Description
DEFAULT

The request will inherit the app's configured processing mode.

DISPATCH_ONLY

Forces the request to be processed in dispatch mode (without storing contacts and conversations), regardless of the app's configured processing mode.

Responses
200

A successful response.

Response Schema: application/json
object (OptIn)

An Opt-In contains the identity of the recipient which gave its consent to receive messages from Conversation API apps on a given channel.

request_id
string

ID for the asynchronous request, will be generated id if not set in request

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

post/v1/projects/{project_id}/optins:register
Request samples
application/json
{
  • "app_id": "{APP_ID}",
  • "channels": [
    • "WHATSAPP"
    ],
  • "recipient": {
    • "contact_id": "{CONTACT_ID}"
    }
}
Response samples
application/json
{
  • "opt_in": {
    • "app_id": "{APP_ID}",
    • "channels": [
      ],
    • "recipient": {
      },
    • "processing_strategy": "DEFAULT"
    },
  • "request_id": "string"
}

Register an opt-out

This method is asynchronous - it returns immediately the requested OptOut registration with any defaults resolved. All changes of the actual opt-out status are then delivered as callbacks to registered webhooks with trigger OPT_OUT.

Request
Security:
Basic
or
oAuth2
path Parameters
project_id
required
string

The unique ID of the project. You can find this on the Sinch Dashboard.

query Parameters
request_id
string

ID for the asynchronous request, will be generated if not set. Currently this field is not used for idempotency but it will be added in v1.

Request Body schema: application/json

The opt-out request.

app_id
required
string

The app for which the Opt-Out is being registered.

channels
required
Array of strings (Channel Identifier)

The channels covered by this Opt-Out. The default are all the channels for a contact if recipient is contact_id or the channels in the channel_identities list.

Items Enum: "WHATSAPP" "RCS" "SMS" "MESSENGER" "VIBER" "VIBERBM" "MMS" "INSTAGRAM" "TELEGRAM" "KAKAOTALK" "LINE" "WECHAT"
required
contact_id (object) or identified_by (object)

The recipient to opt-out. Requires either contact_id or identified_by. If Dispatch Mode is used, only identified_by is allowed.

processing_strategy
string (ProcessingStrategy)

Overrides the app's Processing Mode. Default value is DEFAULT.

Enum: Description
DEFAULT

The request will inherit the app's configured processing mode.

DISPATCH_ONLY

Forces the request to be processed in dispatch mode (without storing contacts and conversations), regardless of the app's configured processing mode.

Responses
200

A successful response.

Response Schema: application/json
object (OptOut)

An Opt-Out contains the identity of the recipient which retract its consent to receive messages from Conversation API apps on a given channel.

request_id
string

ID for the asynchronous request, will be generated id if not set in request

400

Malformed request

401

Incorrect credentials

403

Correct credentials but you don't have access to the requested resource

500

Correct credentials but you don't have access to the requested resource

501

Something went wrong on our end, try again with exponential back-off

post/v1/projects/{project_id}/optouts:register
Request samples
application/json
{
  • "app_id": "{APP_ID}",
  • "channels": [
    • "WHATSAPP"
    ],
  • "recipient": {
    • "contact_id": "{CONTACT_ID}"
    }
}
Response samples
application/json
{
  • "opt_out": {
    • "app_id": "{APP_ID}",
    • "channels": [
      ],
    • "recipient": {
      },
    • "processing_strategy": "DEFAULT"
    },
  • "request_id": "string"
}
SecurityPrivacyLegal & ComplianceCookie Statement
© 2022 Sinch. All rights reserved.