Send a text message with the Shout API

Easily send a text message from your Shout text or toll-free phone number

Shout makes it easy to send text messages from your Shout text (also known as customer service) and toll-free (aka marketing) phone numbers via a simple HTTP Post call. The Shout API will return a message ID and details about the message. Store the ID if you need to check or update the message later.

How Shout creates messages

Shout manages many types of messages and each type of message has its own unique requirements when it is created such as rate limits and whether it should deliver a push notification to a recipient using the Shout App. When Shout receives a request to create a message, it will automatically handle creation of the message, assigning it to the appropriate conversation, and delivering the message to third party providers such as telecom carriers. Each api call to create a Shout message immediately generates a message ID and then is assigned to a background queue to finish message creation and delivery.

Steps to send text messages

To send a text message using the Shout API, you can follow the steps below:

Get an API key from Shout by signing up for an account here and creating an API key. You'll need this API key to authenticate your requests.
Once you have your API key, you can send a text message by making a POST request to the Shout API endpoint with the following information:

outlet_typeThe texting outlet you want to use to send the text message. It can be either "text" or "toll-free". Make sure that the Shout account has a text or toll-free number registered and assigned to it.
profile_idThe id of the profile (aka contact) of the recipient.
body(Optional) The text messaage you want to send.
attachment_urls(Optional) A list of URLS of media files to include in the message (e.g. images, videos, files).

Make sure that each of the keys above are wrapped as a message object. Here's an example of how you could send a text message using the Shout API.

Language

Variant

Example Input

{
  "message": {
    "attachment_urls": [
      "https://example.com/image1.jpg"
    ],
    "body": "Hello, world!",
    "outlet_type": "text",
    "profile_id": "123456"
  }
}

curl https://www.shout.app/api/v20210901/messages/send_text_message -X POST \
-u username:password \
-d "{\"message\":{\"attachment_urls\":[\"https://example.com/image1.jpg\"],\"body\":\"Hello, world!\",\"outlet_type\":\"text\",\"profile_id\":\"123456\"}}"

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://www.shout.app/api/v20210901/messages/send_text_message")
uri.query = {"message":{"attachment_urls":["https://example.com/image1.jpg"],"body":"Hello, world!","outlet_type":"text","profile_id":"123456"}}
request = Net::HTTP::Post.new(uri)
request.basic_auth("username", "password")
request.body = JSON.dump({"message":{"attachment_urls":["https://example.com/image1.jpg"],"body":"Hello, world!","outlet_type":"text","profile_id":"123456"}})

req_options = { use_ssl: uri.scheme == "https" }

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

import requests
from requests.structures import CaseInsensitiveDict

url = "https://www.shout.app/api/v20210901/messages/send_text_message"

headers = {
  "Content-Type": "application/json",
}
data = '{"message":{"attachment_urls":["https://example.com/image1.jpg"],"body":"Hello, world!","outlet_type":"text","profile_id":"123456"}}'

response = requests.post(url, headers=headers, data=data, auth=('username', 'password'))

print(response.status_code)

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.shout.app/api/v20210901/messages/send_text_message');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"message\":{\"attachment_urls\":[\"https://example.com/image1.jpg\"],\"body\":\"Hello, world!\",\"outlet_type\":\"text\",\"profile_id\":\"123456\"}}");

$headers = array();
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_USERPWD, 'username' . ':' . 'password');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
  echo 'Error:' . curl_error($ch);
}
curl_close($ch);

import javax.xml.bind.DatatypeConverter;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {

  public static void main(String[] args) throws IOException {
    URL url = new URL("https://www.shout.app/api/v20210901/messages/send_text_message");
    HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
    httpConn.setRequestMethod("POST");

    byte[] message = ("username:password").getBytes("UTF-8");
    String basicAuth = DatatypeConverter.printBase64Binary(message);
    httpConn.setRequestProperty("Authorization", "Basic " + basicAuth);

    httpConn.setDoOutput(true);
    OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
    writer.write("{\"message\":{\"attachment_urls\":[\"https://example.com/image1.jpg\"],\"body\":\"Hello, world!\",\"outlet_type\":\"text\",\"profile_id\":\"123456\"}}");
    writer.flush();
    writer.close();
    httpConn.getOutputStream().close();

    InputStream responseStream = httpConn.getResponseCode() / 100 == 2
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
    Scanner s = new Scanner(responseStream).useDelimiter("\A");
    String response = s.hasNext() ? s.next() : "";
    System.out.println(response);
  }
}

var request = require('request');

var headers = {
};

var dataString = '{"message":{"attachment_urls":["https://example.com/image1.jpg"],"body":"Hello, world!","outlet_type":"text","profile_id":"123456"}}';

var options = {
    url: 'https://www.shout.app/api/v20210901/messages/send_text_message',
    method: 'POST',
    headers: headers,
    body: dataString,
    auth: {
        'user': 'username',
        'pass': 'password'
    }
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

package main

import (
  "fmt"
  "io/ioutil"
  "log"
  "net/http"
  "strings"
)

func main() {
  client := &http.Client{}
  var data = strings.NewReader(`{"message":{"attachment_urls":["https://example.com/image1.jpg"],"body":"Hello, world!","outlet_type":"text","profile_id":"123456"}}`)
  req, err := http.NewRequest("POST", "https://www.shout.app/api/v20210901/messages/send_text_message", data)
  if err != nil {
    log.Fatal(err)
  }
  req.SetBasicAuth("username", "password")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  bodyText, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%s\n", bodyText)
}

using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.shout.app/api/v20210901/messages/send_text_message"))
    {
        var base64authorization = Convert.ToBase64String(Encoding.ASCII.GetBytes("username:password"));
        request.Headers.TryAddWithoutValidation("Authorization", $"Basic {base64authorization}"); 


        request.Content = new StringContent({"message":{"attachment_urls":["https://example.com/image1.jpg"],"body":"Hello, world!","outlet_type":"text","profile_id":"123456"}});
        request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/x-www-form-urlencoded");

        var response = await httpClient.SendAsync(request);
    }
}

Example Response

{
  "id": 1234,
  "body": "Hello, world!",
  "object": "message",
  "outlet_type": "text",
  "profile_id": "123456",
  "send_status": "will_send"
}

Example Input

{
  "message": {
    "attachment_urls": [
      "https://example.com/image2.jpg"
    ],
    "outlet_type": "toll_free",
    "profile_id": "234567"
  }
}

curl https://www.shout.app/api/v20210901/messages/send_text_message -X POST \
-u username:password \
-d "{\"message\":{\"attachment_urls\":[\"https://example.com/image2.jpg\"],\"outlet_type\":\"toll_free\",\"profile_id\":\"234567\"}}"

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://www.shout.app/api/v20210901/messages/send_text_message")
uri.query = {"message":{"attachment_urls":["https://example.com/image2.jpg"],"outlet_type":"toll_free","profile_id":"234567"}}
request = Net::HTTP::Post.new(uri)
request.basic_auth("username", "password")
request.body = JSON.dump({"message":{"attachment_urls":["https://example.com/image2.jpg"],"outlet_type":"toll_free","profile_id":"234567"}})

req_options = { use_ssl: uri.scheme == "https" }

response = Net::HTTP.start(uri.hostname, uri.port, req_options) do |http|
  http.request(request)
end

# response.code
# response.body

import requests
from requests.structures import CaseInsensitiveDict

url = "https://www.shout.app/api/v20210901/messages/send_text_message"

headers = {
  "Content-Type": "application/json",
}
data = '{"message":{"attachment_urls":["https://example.com/image2.jpg"],"outlet_type":"toll_free","profile_id":"234567"}}'

response = requests.post(url, headers=headers, data=data, auth=('username', 'password'))

print(response.status_code)

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://www.shout.app/api/v20210901/messages/send_text_message');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);

curl_setopt($ch, CURLOPT_POSTFIELDS, "{\"message\":{\"attachment_urls\":[\"https://example.com/image2.jpg\"],\"outlet_type\":\"toll_free\",\"profile_id\":\"234567\"}}");

$headers = array();
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_USERPWD, 'username' . ':' . 'password');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$result = curl_exec($ch);
if (curl_errno($ch)) {
  echo 'Error:' . curl_error($ch);
}
curl_close($ch);

import javax.xml.bind.DatatypeConverter;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStreamWriter;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Scanner;

class Main {

  public static void main(String[] args) throws IOException {
    URL url = new URL("https://www.shout.app/api/v20210901/messages/send_text_message");
    HttpURLConnection httpConn = (HttpURLConnection) url.openConnection();
    httpConn.setRequestMethod("POST");

    byte[] message = ("username:password").getBytes("UTF-8");
    String basicAuth = DatatypeConverter.printBase64Binary(message);
    httpConn.setRequestProperty("Authorization", "Basic " + basicAuth);

    httpConn.setDoOutput(true);
    OutputStreamWriter writer = new OutputStreamWriter(httpConn.getOutputStream());
    writer.write("{\"message\":{\"attachment_urls\":[\"https://example.com/image2.jpg\"],\"outlet_type\":\"toll_free\",\"profile_id\":\"234567\"}}");
    writer.flush();
    writer.close();
    httpConn.getOutputStream().close();

    InputStream responseStream = httpConn.getResponseCode() / 100 == 2
        ? httpConn.getInputStream()
        : httpConn.getErrorStream();
    Scanner s = new Scanner(responseStream).useDelimiter("\A");
    String response = s.hasNext() ? s.next() : "";
    System.out.println(response);
  }
}

var request = require('request');

var headers = {
};

var dataString = '{"message":{"attachment_urls":["https://example.com/image2.jpg"],"outlet_type":"toll_free","profile_id":"234567"}}';

var options = {
    url: 'https://www.shout.app/api/v20210901/messages/send_text_message',
    method: 'POST',
    headers: headers,
    body: dataString,
    auth: {
        'user': 'username',
        'pass': 'password'
    }
};

function callback(error, response, body) {
    if (!error && response.statusCode == 200) {
        console.log(body);
    }
}

request(options, callback);

package main

import (
  "fmt"
  "io/ioutil"
  "log"
  "net/http"
  "strings"
)

func main() {
  client := &http.Client{}
  var data = strings.NewReader(`{"message":{"attachment_urls":["https://example.com/image2.jpg"],"outlet_type":"toll_free","profile_id":"234567"}}`)
  req, err := http.NewRequest("POST", "https://www.shout.app/api/v20210901/messages/send_text_message", data)
  if err != nil {
    log.Fatal(err)
  }
  req.SetBasicAuth("username", "password")
  resp, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()
  bodyText, err := ioutil.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Printf("%s\n", bodyText)
}

using (var httpClient = new HttpClient())
{
    using (var request = new HttpRequestMessage(new HttpMethod("POST"), "https://www.shout.app/api/v20210901/messages/send_text_message"))
    {
        var base64authorization = Convert.ToBase64String(Encoding.ASCII.GetBytes("username:password"));
        request.Headers.TryAddWithoutValidation("Authorization", $"Basic {base64authorization}"); 


        request.Content = new StringContent({"message":{"attachment_urls":["https://example.com/image2.jpg"],"outlet_type":"toll_free","profile_id":"234567"}});
        request.Content.Headers.ContentType = MediaTypeHeaderValue.Parse("application/x-www-form-urlencoded");

        var response = await httpClient.SendAsync(request);
    }
}

Example Response

{
  "id": 1234,
  "object": "message",
  "outlet_type": "text",
  "profile_id": "123456",
  "send_status": "will_send"
}

Make sure to customize the data dictionary with the specific details of your messageand replace YOUR_API_KEY_HERE with your actual API key. You may need to change the Authorization header to match your authentication type.

The Shout API will respond with a JSON object containing details about the message, including its ID and status.

API References for this guide

POST /messages/send_text_message

Send a text message with the Shout API

How Shout creates messages

Steps to send text messages

API References for this guide

Related Guides

Links