Multichannel message

post

https://api.octopush.com/v1/public/multi-channel/send

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} 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

Name	Type	Description
channel	string	Channel to send [‘sms’, ‘voice_sms’, ‘rcs’, ‘email’]
text	string	Message text (from 1 to 1224 characters).
recipients	array	[{'phone_number': '+111222233334444'},...,{'phone_number': '+2222333334444555'}] or [{'email': '[email protected]'},...,{'email': '[email protected]'}] for email channel
sender	string	Sender of the message (if the user allows it), 3-11 alphanumeric characters (a-zA-Z0-9).
send_at	string	When you want to send the campaign. Format: DateTime ISO8601 (for ex: "2018-10-03T07:42:39-07:00").
purpose	string	Campaign purpose: (transactional/alert or marketing) : ['alert','wholesale'].
list_name	string	This is the value representing to list name you want to create for those contacts
simulation_mode	boolean	(optional) If this value is 'true', your request will be simulated, and you will receive a fake result. Only some minimal validations will be executed.
recipient_tracking	boolean	"True" for getting back recipient tracking.
auto_optimize_text	boolean	By transmitting this field with "false" value, your text will not be optimized by Octopush robot (your message could contain unicode characters, or useless spaces that could increase the number of needed SMS for each contact).
auto_remove_blacklisted_contacts	boolean	This value is "true" when you want to send with ignore blacklisted contacts.
Metadata
- metadata.type	string	Campaign Type: ['sms_premium','sms_low_cost'] of the SMS Campaign; ['voice_sms'] of the Voice VMS Campaign
- metadata.with_replies	boolean	"True" for getting back recipient replies
- metadata.voice_gender	string	Voice gender [‘male’, ‘female’].
- metadata.voice_language	string	Voice Language [‘en-US’, ‘en-GB’, ‘el-GR’, ‘pl-PL’, ‘hu-HU’, ‘sv-SE’, ‘de-DE’, ‘es-ES’, ‘es-LA’, ‘fr-FR’, ‘it-IT’, ‘pt-BR’, ‘ru-RU’].
- metadata.get_back_pressed_keys	boolean	This value is "true" when you want to get back pressed key.
- metadata.request_id	string	(optional) To avoid sending same request multiple times, set up a request ID. In case the duplication will be detected, a validation error will be returned. A request_id will expire after 24 hours.
- metadata.emailing_service	string	The emailing service for the email channel [‘mailbox’, ‘gateway’].
- metadata.email_from	string	The sender's email address for the email channel.
- metadata.name_from	string	The sender's name for the email channel.
- metadata.subject	string	The subject for the email channel (max 1000 characters).
- metadata.template_name	string	The template name used for the email channel.
- metadata.body_format	string	The email body format: ‘plain_text’ (default) or ‘html’. Applies only to the text field, not metadata.template_name.
- metadata.language	string	The language used for the unsubscription mention in the email channel.
- metadata.message_type	string	The type of RCS message [‘simple_text’, ‘rich_card’]. Default is simple_text, for the RCS channel.
- metadata.cards	array	Defines visual cards with media and content, used when message_type is rich_card, for the RCS channel.
- metadata.actions	array	Defines interactive options (e.g., buttons), used when message_type is simple_text, for the RCS channel.

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_remove_blacklisted_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_remove_blacklisted_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.

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

Email Campaign

{
   "channel": "email",
   "text": "This is the content of your email.",
   "recipients": [
       {"email": "[email protected]"},
       {"email": "[email protected]"}
   ],
   "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",
       "subject": "Test Email",
       "emailing_service": "gateway",
       "template_name": "welcome_email_template"
   }
}

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."
}