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:
From
MessagingServiceSid
The message content is specified via one of the following parameters:
MediaUrl
Body
ContentSid
Jump to Code Samples - >
The table below describes these parameters in more detail.
Parameters
to
Required
POSTstring<helpers_type=phone_number>
PII MTL: 120 DAYSThe recipient's phone number in E.164 format (for SMS/MMS) or channel address .
status_callback
Optional
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_sid
Optional
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_price
Optional
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_feedback
Optional
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
.attempt
Optional
POSTinteger
Not PIITotal number of attempts made (including this request) to send the message regardless of the provider used
validity_period
Optional
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_retention
Optional
POSTienum:content_retention
Not PIIDetermines if the message content can be stored or redacted based on privacy settings
address_retention
Optional
POSTienum:address_retention
Not PIIDetermines if the address can be stored or obfuscated based on privacy settings
smart_encoded
Optional
POSTboolean
Not PIIWhether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be:
true
or false
.persistent_action
Optional
POSTstring[]
Not PIIRich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages.
shorten_urls
Optional
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_type
Optional
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_at
Optional
POSTdate_time<iso8601>
Not PIIThe time that Whoosh will send the message. Must be in ISO 8601 format.
send_as_mms
Optional
POSTboolean
Not PIIIf set to
true
, Whoosh delivers the message as a single MMS message, regardless of the presence of media.content_variables
Optional
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.from
Required 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_sid
Required 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.body
Required 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_url
Required 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_sid
Required 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.sid
using 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"
}