Encoding : UTF-8

Authentication

Your "api-key" and "api-login" identifiers must be added in the headers.

Definition

This sends a multi channel {SMS/Voice SMS/RCS/Email/Live Chat} in modes:

• simple (1 contact)
• campaign (up to 500 contacts)
  You must indicate your phone numbers in the "recipients" parameter, which is an array containing objects of type "contact".

Special parameters

How Our API Deals With Incorrect Data

The API we provide will try to interpret your request as best it can. If a parameter has the wrong value, we will try to understand it anyway. If the parameter has the wrong type, we will try to format it as best we can. Thus, we have determined default values, which are indicated in our documentation. If a parameter could not be recognized or "fixed", we will ignore it, but your request will be sent.
If one of your parameters does not have the right value, or does not have the right type, we will try to:

• "cast" (convert) it so that it can be understood.
• format it (delete prohibited characters for example)

Important Considerations

Be careful with the number of contacts per request. For campaigns, a good use is to transmit several frames of 200 to 500 numbers at a time.

• < 200: you multiply calls and waste connection time.
• 500: the frame becomes heavy and the risk of data loss increases.

Request Body Example in JSON

SMS Campaign

{
   "channel": "sms",
   "text": "Hello, this is a test message.",
   "recipients": [
       {"phone_number": "+33111222333"},
       {"phone_number": "+33111222334"}
   ],
   "sender": "SenderName",
   "send_at": "2024-12-19T10:00:00-07:00",
   "purpose": "alert",
   "list_name": "sms_list",
   "simulation_mode": false,
   "recipient_tracking": true,
   "auto_optimize_text": true,
   "auto_delete_optout_contacts": true,
   "metadata": {
       "type": "sms_premium",
       "with_replies": true
   }
}

Voice SMS Campaign

{
   "channel": "voice_sms",
   "text": "Hello, this is a voice message test.",
   "recipients": [
       {"phone_number": "+33111222333"},
       {"phone_number": "+33111222334"}
   ],
   "sender": "SenderName",
   "send_at": "2024-12-19T10:00:00-07:00",
   "purpose": "alert",
   "list_name": "voice_sms_list",
   "simulation_mode": false,
   "auto_delete_optout_contacts": true,
   "metadata": {
       "type": "voice_sms",
       "voice_gender": "male",
       "voice_language": "en-US",
       "get_back_pressed_keys": true
   }
}

RCS Campaign

*Info In order to use this channel, you must first create your 'identity' that will be validated by Google. It's called an 'Agent'. And the agent creation wizard is available on your Octopush client back office.
You can also specify which RCS agent to use for this request by setting the sender field with the RCS agent name. If sender is not provided, the system will use the default RCS agent that you configured. You can find this name on the Multichannel settings page.
When metadata.template_name is provided, the text field is optional and can be empty. The message content is taken from the RCS template configured in your Octopush account.

{
   "channel": "rcs",
   "text": "Hello, this is a test RCS message.",
   "recipients": [
       {"phone_number": "+33111222333"},
       {"phone_number": "+33111222334"}
   ],
   "sender": "***",
   "send_at": "2024-12-19T10:00:00-07:00",
   "purpose": "alert",
   "list_name": "rcs_list",
   "simulation_mode": false,
   "auto_delete_optout_contacts": true,
   "metadata": {
       "with_replies": true
   }
}

RCS Campaign with template

{
   "channel": "rcs",
   "text": "",
   "recipients": [
       {"phone_number": "+33111222333"}
   ],
   "send_at": "2024-12-19T10:00:00-07:00",
   "purpose": "alert",
   "metadata": {
       "template_name": "welcome_rcs_template"
   }
}

Email Campaign

{
   "channel": "email",
   "text": "This is the content of your email.",
   "recipients": [
       {"email": "[email protected]", "authorize_tracking_pixel": true},
       {"email": "[email protected]", "authorize_tracking_pixel": false}
   ],
   "sender": "SenderName",
   "send_at": "2024-12-19T10:00:00-07:00",
   "purpose": "alert",
   "list_name": "email_list",
   "metadata": {
       "email_from": "[email protected]",
       "name_from": "Sender Name",
       "cc_emails": ["[email protected]", "[email protected]"],
       "bcc_emails": ["[email protected]"],
       "subject": "Test Email",
       "emailing_service": "gateway",
       "template_name": "welcome_email_template",
       "opening_click_tracking": true,
       "per_contact_tracking": true,
       "track_unknown_consents": false,
       "unsubscribe_link": true
   }
}

Live Chat Message

*Info For the 'live_chat' channel:

• Each recipient must have at least one of phone_number, email or conversation_id.
• When conversation_id is provided (UUID v4), the API will try to send the message using this conversation.
• If the provided conversation_id does not match any conversation but phone_number or email is present for the same recipient, the API will fallback and try to resolve the Live Chat contact by phone_number/email.
• At least one valid recipient must be resolved, otherwise a [recipients] field does not contain any valid recipient. error will be returned.

{
   "channel": "live_chat",
   "text": "Hello, this is a live chat message.",
   "recipients": [
       {
           "phone_number": "+33111222333"
       },
       {
           "email": "[email protected]"
       },
       {
           "conversation_id": "00000000-0000-0000-0000-000000000001"
       }
   ],
   "sender": "AgentName"
}

Server Response Example in JSON

Success of a SMS campaign

{
   "sms_ticket": "sms_5f3fbce61266e",
   "number_of_contacts": 5,
   "total_cost": 5.00502839,
   "number_of_sms_needed": 5,
   "residual_credit": 50.75,
   "message": "******"
}

Bad request from an SMS campaign

{
   "code": 121,
   "message": "Mention STOP is missing."
}

Success of a Voice SMS campaign

{
   "ticket_number": "voice_5f44ebf9e47b7",
   "number_of_contacts": 1,
   "total_cost": 0.05,
   "estimated_duration": 30,
   "residual_credit": 149.95
}

Bad request from a Voice campaign

{
   "code": 400,
   "message": "Payload validation error.",
   "errors":
   {
      "voice_language":
      {
         "code": 442,
         "message": "Voice language not supported."
      }
   }
}

Success of a Email campaign

{
   "ticket_number": "email_5f44ebf9e47b7",
   "number_of_contacts": 1,
   "total_cost": 0.05,
   "residual_credit": 149.95
}

Bad request from a Email campaign

{
   "code": 2005,
   "message": "[destination email] field should be valid."
}

Success of a Live chat message

{
   "ticket_number": null,
   "number_of_contacts": 1,
   "total_cost": 0.0,
   "residual_credit": 149.95
}