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 the To 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

Parameters in REST API format
account_sid

Path

POST sid<AC> Not PII

The SID of the Account creating the Message resource.

to

Required

POST string<helpers_type=phone_number> PII MTL: 120 DAYS

The recipient's phone number in E.164 format (for SMS/MMS) or channel address .

status_callback

Optional

POST string<helpers_type=url> Not PII

The 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

POST sid<AP> Not PII

The 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

POST currency<helpers_type=decimal> Not PII

The 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

POST boolean Not PII

Boolean 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

POST integer Not PII

Total number of attempts made (including this request) to send the message regardless of the provider used

validity_period

Optional

POST integer Not PII

The 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.
force_delivery

Optional

POST boolean Not PII

Reserved

content_retention

Optional

POST ienum:content_retention Not PII

Determines if the message content can be stored or redacted based on privacy settings

address_retention

Optional

POST ienum:address_retention Not PII

Determines if the address can be stored or obfuscated based on privacy settings

smart_encoded

Optional

POST boolean Not PII

Whether to detect Unicode characters that have a similar GSM-7 character and replace them. Can be: true or false.
persistent_action

Optional

POST string[] Not PII

Rich actions for non-SMS/MMS channels. Used for sending location in WhatsApp messages.

shorten_urls

Optional

POST boolean Not PII

For 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

POST ienum:schedule_type Not PII

For 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

POST date_time<iso8601> Not PII

The time that Whoosh will send the message. Must be in ISO 8601 format.

send_as_mms

Optional

POST boolean Not PII

If set to true, Whoosh delivers the message as a single MMS message, regardless of the presence of media.
content_variables

Optional

POST string Not PII

For 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

POST string<helpers_type=phone_number> PII MTL: 120 DAYS

The 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

POST sid<MG> Not PII

The 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

POST string PII MTL: 30 DAYS

The 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

POST url[] PII MTL: 30 DAYS

The 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

POST sid<HX> Not PII

For 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's Status 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.
PropertyDescription
MessageStatusThe Status of the Message resource at the time the status callback request was sent.
ErrorCodeIf 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 a Status of delivered or undelivered, Whoosh's request to the StatusCallback URL contains an additional property:
PropertyDescription
RawDlrDoneDateThis 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.
NODE.JSPYTHONJAVARUBYC#
Copy
Copied
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));      
Copy
Copied
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)
Copy
Copied
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);

    }
}
Copy
Copied
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
Copy
Copied
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
Copy
Copied
{
  "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"
}