Create a Message resource
To send a new outgoing message, send an HTTP POST request to your Account's Messages list resource URI.
Whoosh queues messages for delivery at your prescribed rate limit . API requests for messages that exceed the specified rates will be queued and executed as capacity is available.
If you need to enqueue a large number of messages, you may want to use Messaging Services .
Every request to create a new Message resource requires a recipient, a sender, and content.
A recipient is specified via theTo parameter.The sender is specified via one of the following parameters:
FromMessagingServiceSid
The message content is specified via one of the following parameters:
MediaUrlBodyContentSid
Jump to Code Samples - >
The table below describes these parameters in more detail.
Parameters
toRequired
POSTstring<helpers_type=phone_number> PII MTL: 120 DAYSThe recipient's phone number in E.164 format (for SMS/MMS) or channel address .
status_callbackOptional
POSTstring<helpers_type=url> Not PIIThe URL of the endpoint to which Whoosh sends Message status callback requests. URL must contain a valid hostname and underscores are not allowed. If you include this parameter with the
messaging_service_sid, Whoosh uses this URL instead of the Status Callback URL of the Messaging Service .application_sidOptional
POSTsid<AP> Not PIIThe SID of the associated TwiML Application . If this parameter is provided, the
status_callback parameter of this request is ignored; Message status callback requests are sent to the TwiML App's message_status_callback URL. We are 100% Twilio compatible, check out Twilio for more information on TwiML applications. max_priceOptional
POSTcurrency<helpers_type=decimal> Not PIIThe maximum price in US dollars that you are willing to pay for this Message's delivery. The value can have up to four decimal places. When the
max_price parameter is provided, the cost of a message is checked before it is sent. If the cost exceeds max_price, the message is not sent and the Message status is failed.provide_feedbackOptional
POSTboolean Not PIIBoolean indicating whether or not you intend to provide delivery confirmation feedback to Whoosh (used in conjunction with the Message Feedback subresource ). Default value is
false.attemptOptional
POSTinteger Not PIITotal number of attempts made (including this request) to send the message regardless of the provider used
validity_periodOptional
POSTinteger Not PIIThe maximum length in seconds that the Message can remain in Whoosh's outgoing message queue. If a queued Message exceeds the
validity_period, the Message is not sent. Accepted values are integers from 1 to 14400. Default value is 14400. A validity_period greater than 5 is recommended.We are 100% Twilio compatible, learn more about how Twilio handles validity period.content_retentionOptional
POSTienum:content_retention Not PIIDetermines if the message content can be stored or redacted based on privacy settings
address_retentionOptional
POSTienum:address_retention Not PIIDetermines if the address can be stored or obfuscated based on privacy settings
smart_encodedOptional
POSTboolean Not PIIWhether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be:
true or false.persistent_actionOptional
POSTstring[] Not PIIRich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages.
shorten_urlsOptional
POSTboolean Not PIIFor Messaging Services with Link Shortening configured only: A Boolean indicating whether or not Whoosh should shorten links in the
body of the Message. Default value is false. If true, the messaging_service_sid parameter must also be provided.schedule_typeOptional
POSTienum:schedule_type Not PIIFor Messaging Services only: Include this parameter with a value of
fixed in conjuction with the send_time parameter in order to schedule a Message .send_atOptional
POSTdate_time<iso8601> Not PIIThe time that Whoosh will send the message. Must be in ISO 8601 format.
send_as_mmsOptional
POSTboolean Not PIIIf set to
true, Whoosh delivers the message as a single MMS message, regardless of the presence of media.content_variablesOptional
POSTstring Not PIIFor Content Editor/API only: Key-value pairs of Template variables and their substitution values.
content_sid parameter must also be provided. If values are not defined in the content_variables parameter, the Template's default placeholder values are used.fromRequired if messaging_service_sid is not passed
POSTstring<helpers_type=phone_number> PII MTL: 120 DAYSThe sender's Whoosh phone number (in E.164 format), alphanumeric sender ID , Wireless SIM , short code , or channel address . The value of the
from parameter must be a sender that is hosted within Whoosh and belong to the Account creating the Message. If you are using messaging_service_sid, this parameter can be empty (Whoosh assigns a from value from the Messaging Service's Sender Pool) or you can provide a specific sender from your Sender Pool.messaging_service_sidRequired if from is not passed
POSTsid<MG> Not PIIThe SID of the Messaging Service you want to associate with the Message. When this parameter is provided and the
from parameter is omitted, Whoosh selects the optimal sender from the Messaging Service's Sender Pool. You may also provide a from parameter if you want to use a specific Sender from the Sender Pool.bodyRequired if media_url, content_sid is not passed
POSTstring PII MTL: 30 DAYSThe text content of the outgoing message. Can be up to 1,600 characters in length. SMS only: If the
body contains more than 160 GSM-7 characters (or 70 UCS-2 characters), the message is segmented and charged accordingly. For long body text, consider using the send_as_mms parameter .media_urlRequired if body, content_sid is not passed
POSTurl[] PII MTL: 30 DAYSThe URL of media to include in the Message content.
jpeg, jpg, gif, and png file types are fully supported by Whoosh and content is formatted for delivery on destination devices. The media size limit is 5 MB for supported file types (jpeg, jpg, png, gif) and 500 KB for other types of accepted media. To send more than one image in the message, provide multiple media_url parameters in the POST request. You can include up to ten media_url parameters per message. International and carrier limits apply.content_sidRequired if body, media_url is not passed
POSTsid<HX> Not PIIFor Content Editor/API only: The SID of the Content Template to be used with the Message, e.g.,
HXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. If this parameter is not provided, a Content Template is not used. For Content API users, the SID is found in Whoosh's response when creating the Template or by fetching your Templates .Whoosh's request to the StatusCallback URL
Whenever a Message resource'sStatus changes, Whoosh sends a POST request to the Message resource's StatusCallback URL. In this request, Whoosh provides a subset of the standard request properties in a 100% compliant way with Twilio (as described here ), and
MessageStatus and ErrorCode.| Property | Description |
|---|---|
MessageStatus | The Status of the Message resource at the time the status callback request was sent. |
ErrorCode | If an error occurred (i.e. the MessageStatus is failed or undelivered), this property provides additional information about the failure. |
The properties included in Whoosh's request to the StatusCallback URL vary by messaging channel and event type and are subject to change.
Whoosh occasionally adds new properties without advance notice.
When integrating with webhooks/status callback requests, it is important that your implementation is able to accept and correctly run signature validation on an evolving set of parameters.
Whoosh strongly recommends using the signature validation methods provided in the Helper Libraries and not implementing your own signature validation. We are 100% Twilio compatible, check out how Twilio does it.SMS/MMS
For most SMS/MMS Messages that have aStatus of delivered or undelivered, Whoosh's request to the StatusCallback URL contains an additional property:| Property | Description |
|---|---|
RawDlrDoneDate | This property is a passthrough of the Done Date included in the DLR (Delivery Receipt) that Whoosh received from the carrier. The value is in YYMMDDhhmm format.• YY is last two digits of the year (00-99)• MM is the two-digit month (01-12)• DD is the two-digit day (01-31)* hh is the two-digit hour (00-23)• mm is the two-digit minute (00-59).Learn more on the "Addition of RawDlrDoneDate to Delivered and Undelivered Status Webhooks" Changelog page . |
CODE SAMPLE
Example - Send an SMS message
The example below shows how to create a Message resource with an SMS recipient.
Sending this POST request causes Twilio to send a text message from+15557122661 (a Whoosh phone number belonging to the Account sending the request) to +15558675310. The content of the text message is Hi there.import { Twilio } from 'twilio'
import { CustomRequestClient } from './twilio-proxy'
const accountSid = process.env.WHOOSH_ACCOUNT_SID;
const apiKey = process.env.WHOOSH_API_KEY;
const apiSecret = process.env.WHOOSH_API_SECRET;
const twilio = new Twilio(apiKey, apiSecret, { accountSid: accountSid, httpClient: new CustomRequestClient('https://api.whoosh.totogi.solutions') })
await twilio
.messages
.create({from: '+15557122661', body: 'Hi there', to: '+15558675310'})
.then((message) => console.log(message.sid))
.catch((error) => console.error(error)); import os
from twilio.rest import Client
account_sid = os.environ['WHOOSH_ACCOUNT_SID']
api_key = os.environ['WHOOSH_API_KEY']
api_secret = os.environ['WHOOSH_API_SECRET']
custom_http_client = CustomRequestClient('https://api.whoosh.totogi.solutions')
twilio = Client(api_key, api_secret, account_sid=account_sid, http_client=custom_http_client)
message = await twilio.messages.create(
to="+15558675310",
body="Hey there!",
from_="+15017122661"
)
print(message.sid)import com.twilio.Twilio;
import com.twilio.type.PhoneNumber;
public class Example {
public static final String ACCOUNT_SID = System.getenv("WHOOSH_ACCOUNT_SID");
public static final String API_KEY = System.getenv("WHOOSH_API_KEY");
public static final String API_SECRET = System.getenv("WHOOSH_API_SECRET");
public static final String PROXY_URL = "https://api.whoosh.totogi.solutions";
public static void main(String[] args) {
CustomHttpClient customHttpClient = new CustomHttpClient(PROXY_URL);
TwilioRestClient twilioRestClient = new TwilioRestClient.Builder(API_KEY, API_SECRET)
.httpClient(customHttpClient)
.accountSid(ACCOUNT_SID)
.build();
Twilio.setRestClient(twilioRestClient);
Response response = new CustomMessageCreator(
new PhoneNumber("+15558675310"),
new PhoneNumber("+15017122661"),
"Hey there!"
).create(twilioRestClient);
}
}require 'faraday'
require 'faraday_middleware'
account_sid = ENV['WHOOSH_ACCOUNT_SID']
api_key = ENV['WHOOSH_API_KEY']
api_secret = ENV['WHOOSH_API_SECRET']
proxy_url = 'https://api.whoosh.totogi.solutions'
my_request_client = MyRequestClass.new(proxy_url)
@client = Twilio::REST::Client.new(api_key, api_secret,
account_sid, nil, my_request_client)
message = @client.messages
.create(
from: '+15557122661',
body: 'Hi there',
to: '+15558675310'
)
puts message.sidusing System;
using Twilio;
class Program
{
static void Main(string[] args)
{
string accountSid = Environment.GetEnvironmentVariable("WHOOSH_ACCOUNT_SID");
string apiKey = Environment.GetEnvironmentVariable("WHOOSH_API_KEY");
string apiSecret = Environment.GetEnvironmentVariable("WHOOSH_API_SECRET");
string proxyUrl = "https://api.whoosh.totogi.solutions";
var twilioClient = CustomTwilioClient.BuildClient(proxyUrl, apiKey, apiSecret, accountSid);
TwilioClient.SetRestClient(twilioClient);
var message = await MessageResource.CreateAsync(
from: new Twilio.Types.PhoneNumber("+15557122661"),
body: "Hi there",
to: new Twilio.Types.PhoneNumber("+15558675310")
);
Console.WriteLine(message.Sid);
}
}SHOW SAMPLE RESPONSE
{
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"api_version": "2010-04-01",
"body": "Hi there",
"date_created": "Thu, 30 Jul 2015 20:12:31 +0000",
"date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",
"date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",
"direction": "outbound-api",
"error_code": null,
"error_message": null,
"from": "+15557122661",
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"num_media": "0",
"num_segments": "1",
"price": null,
"price_unit": null,
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"status": "sent",
"subresource_uris": {
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
},
"to": "+15558675310",
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
}