Guides

/api/send

Craft a Project JSON Payload and send to it to one or more phone numbers passed in the phone attribute via HTTP POST.

Suggest Edits

Send a message

SMS

curl -H "Content-Type: application/json" -X POST -d '{
  "phone": ["phone_number"],
  "text" : "Hello Till from cURL!"
}' "https://platform.tillmobile.com/api/send?username=username&api_key=api_key"

# Example Dependencies
# - requests
#    * pip install requests

import os
import requests

till_username = "username"
till_api_key = "api_key"

requests.post(
    "https://platform.tillmobile.com/api/send?username=%s&api_key=%s" % (
        till_username,
        till_api_key
    ), 
    json={
        "phone": ["phone_number"],
        "text" : "Hello Till from Python!"
    }
)

// Example Dependencies
// - request-json
//   * npm install request-json

var request = require("request-json");

var username = "username";
var api_key = "api_key";

request.createClient(
  "https://platform.tillmobile.com"
).post(
  "/api/send?username=" + username + "&api_key=" + api_key, 
  {
    "phone": ["phone_number"],
    "text" : "Hello Till from node.js!"
  }, 
  function(err, res, body) {
    return console.log(res.statusCode);
  }
);

<?php
// # Example Dependencies
// - PHP >= 5.5.36
// - PHP cURL extension
//   * sudo apt-get install php-curl
// - Composer
//   * curl -sS https://getcomposer.org/installer | php
//
// # Install Guzzle HTTP Client
// - php composer.phar require guzzlehttp/guzzle

// Init Composer
require "vendor/autoload.php";

// Load Guzzle HTTP Client
use Guzzle\Http\Client;

// Your Till credentials
$till_username = "username";
$till_api_key = "api_key";

// The Till project body
$till_project = [
	"phone" => ["phone_number"],
	"text" => "Hello Till from PHP!"
];

// Execute HTTP request
$client = new GuzzleHttp\Client();
try {

    $res = $client->request(
        "POST", 
        "https://platform.tillmobile.com/api/send?username=".$till_username."&api_key=".$till_api_key,
        ["body" => json_encode($till_project)]
    );

    // Till HTTP response body
    echo $res->getBody();

} catch(Exception $e) {

    echo $e;

}
?>

import java.net.URL;
import java.net.URLConnection;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.io.InputStream;
import java.io.BufferedInputStream;

public class Till {
    public static String send(String endpoint, String username, String api_key, String json) throws Exception {
        final URL url = new URL(endpoint + "?username=" + username + "&api_key=" + api_key);
        final URLConnection conn = url.openConnection();

        HttpURLConnection http = null;
        try {
            http = (HttpURLConnection)conn;
            http.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
            http.setRequestProperty("Content-Length", "" + json.getBytes().length);
            http.setRequestMethod("POST");
            http.setRequestProperty("User-Agent", "Mozilla/5.0");
            http.setDoOutput(true);
            http.setDoInput(true);
            http.setUseCaches(false);

            OutputStream os = null;
            try {
                os = http.getOutputStream();
                os.write(json.getBytes("UTF-8"));
                os.flush();
            } finally {
                if(os != null) {
                    os.close();
                }
            }

            InputStream in = null;
            try {
                in = new BufferedInputStream(conn.getInputStream());
                byte[] contents = new byte[1024];
                int bytesRead = 0;
                StringBuffer outStr = new StringBuffer(); 
                while((bytesRead = in.read(contents)) != -1) { 
                    outStr.append(new String(contents, 0, bytesRead));
                }
                return outStr.toString();
            } finally {
                if(in != null) {
                    in.close();
                }
            }
        } finally {
            if(http != null) {
                http.disconnect();      
            }
        }
    }

    public static void main(String[] args) {
        try {
            Till.send(
                "https://platform.tillmobile.com/api/send",
                "username",
                "api_key",
                "{\"phone\":[\"phone_number\"], \"text\":\"Hello Till from Java!\"}"
            );
        } catch(Exception e) {
            System.out.println(e.toString());
        }
    }
}

Voice

curl -H "Content-Type: application/json" -X POST -d '{
  "phone": ["phone_number"],
  "method": "VOICE",
  "text" : "Hello Till from cURL!"
}' "https://platform.tillmobile.com/api/send?username=username&api_key=api_key"

Send question(s)

SMS

curl -H "Content-Type: application/json" -X POST -d '{
  "phone": ["phone_number"],
  "introduction": "Hello from Till.",
  "questions" : [{
    "text": "Do you have a few moments to answer a question or two?",
    "tag": "have_a_few_moments",
    "responses": ["Yes", "No"],
    "conclude_on": "No",
    "webhook": "https://yourapp.com/have_a_few_moments_results/"
  },
  {
    "text": "What is your favorite color?",
    "tag": "favorite_color",
    "responses": ["Red", "Green", "Yellow"],
    "webhook": "https://yourapp.com/favorite_color_results/"
  },
  {
    "text": "Who is you favorite Star Wars character?",
    "tag": "favorite_star_wars_character",
    "webhook": "https://yourapp.com/favorite_star_wars_character_results/"
  }],
  "conclusion": "Thank you for your time"
}' "https://platform.tillmobile.com/api/send?username=username&api_key=api_key"

# Example Dependencies
# - requests
#    * pip install requests

import os
import requests

till_username = "username"
till_api_key = "api_key"

requests.post(
    "https://platform.tillmobile.com/api/send?username=%s&api_key=%s" % (
        till_username,
        till_api_key
    ), 
    json={
        "phone": ["phone_number"],
        "introduction": "Hello from Till.",
        "questions" : [{
            "text": "Do you have a few moments to answer a question or two?",
            "tag": "have_a_few_moments",
            "responses": ["Yes", "No"],
            "conclude_on": "No",
            "webhook": "https://yourapp.com/have_a_few_moments_results/"
        },
        {
            "text": "What is your favorite color?",
            "tag": "favorite_color",
            "responses": ["Red", "Green", "Yellow"],
            "webhook": "https://yourapp.com/favorite_color_results/"
        },
        {
            "text": "Who is you favorite Star Wars character?",
            "tag": "favorite_star_wars_character",
            "webhook": "https://yourapp.com/favorite_star_wars_character_results/"
        }],
        "conclusion": "Thank you for your time"
    }
)

// Example Dependencies
// - request-json
//   * npm install request-json

var request = require("request-json");

var username = "username";
var api_key = "api_key";

request.createClient(
  "https://platform.tillmobile.com"
).post(
  "/api/send?username=" + username + "&api_key=" + api_key, 
  {
    "phone": ["phone_number"],
    "introduction": "Hello from Till.",
    "questions" : [{
      "text": "Do you have a few moments to answer a question or two?",
      "tag": "have_a_few_moments",
      "responses": ["Yes", "No"],
      "conclude_on": "No",
      "webhook": "https://yourapp.com/have_a_few_moments_results/"
    },
    {
      "text": "What is your favorite color?",
      "tag": "favorite_color",
      "responses": ["Red", "Green", "Yellow"],
      "webhook": "https://yourapp.com/favorite_color_results/"
    },
    {
      "text": "Who is you favorite Star Wars character?",
      "tag": "favorite_star_wars_character",
      "webhook": "https://yourapp.com/favorite_star_wars_character_results/"
    }],
    "conclusion": "Thank you for your time"
  }, 
  function(err, res, body) {
    return console.log(res.statusCode);
  }
);

<?php
// # Example Dependencies
// - PHP >= 5.5.36
// - PHP cURL extension
//   * sudo apt-get install php-curl
// - Composer
//   * curl -sS https://getcomposer.org/installer | php
//
// # Install Guzzle HTTP Client
// - php composer.phar require guzzlehttp/guzzle

// Init Composer
require "vendor/autoload.php";

// Load Guzzle HTTP Client
use Guzzle\Http\Client;

// Your Till credentials
$till_username = "username";
$till_api_key = "api_key";

// The Till project body
$till_project = [
    "phone" => ["phone_number"],
    "introduction" => "Hello from Till.",
    "questions" => [
        [
            "text" => "Do you have a few moments to answer a question or two?",
            "tag" => "have_a_few_moments",
            "responses" => ["Yes", "No"],
            "conclude_on" => "No",
            "webhook" => "https://yourapp.com/have_a_few_moments_results/"      
        ],
        [
            "text" => "What is your favorite color?",
            "tag" => "favorite_color",
            "responses" => ["Red", "Green", "Yellow"],
            "conclude_on" => "No",
            "webhook" => "https://yourapp.com/favorite_color_results/"      
        ],
        [
            "text" => "Who is you favorite Star Wars character?",
            "tag" => "favorite_star_wars_character",
            "webhook" => "https://yourapp.com/favorite_star_wars_character_results/"
        ]
    ],
    "conclusion" => "Thank you for your time"
];

// Execute HTTP request
$client = new GuzzleHttp\Client();
try {
    
    $res = $client->request(
        "POST", 
        "https://platform.tillmobile.com/api/send?username=".$till_username."&api_key=".$till_api_key,
        ["body" => json_encode($till_project)]
    );

    // Till HTTP response body
    echo $res->getBody();

} catch(Exception $e) {

    echo $e;

}
?>

import java.net.URL;
import java.net.URLConnection;
import java.net.HttpURLConnection;
import java.io.OutputStream;
import java.io.InputStream;
import java.io.BufferedInputStream;

public class Till {
    public static String send(String endpoint, String username, String api_key, String json) throws Exception {
        final URL url = new URL(endpoint + "?username=" + username + "&api_key=" + api_key);
        final URLConnection conn = url.openConnection();

        HttpURLConnection http = null;
        try {
            http = (HttpURLConnection)conn;
            http.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
            http.setRequestProperty("Content-Length", "" + json.getBytes().length);
            http.setRequestMethod("POST");
            http.setRequestProperty("User-Agent", "Mozilla/5.0");
            http.setDoOutput(true);
            http.setDoInput(true);
            http.setUseCaches(false);

            OutputStream os = null;
            try {
                os = http.getOutputStream();
                os.write(json.getBytes("UTF-8"));
                os.flush();
            } finally {
                if(os != null) {
                    os.close();
                }
            }

            InputStream in = null;
            try {
                in = new BufferedInputStream(conn.getInputStream());
                byte[] contents = new byte[1024];
                int bytesRead = 0;
                StringBuffer outStr = new StringBuffer(); 
                while((bytesRead = in.read(contents)) != -1) { 
                    outStr.append(new String(contents, 0, bytesRead));
                }
                return outStr.toString();
            } finally {
                if(in != null) {
                    in.close();
                }
            }
        } finally {
            if(http != null) {
                http.disconnect();      
            }
        }
    }

    public static void main(String[] args) {
        try {
            Till.send(
                "https://platform.tillmobile.com/api/send/",
                "username",
                "api_key",
                "{" +
                "  \"phone\": [\"phone_number\"]," +
                "  \"introduction\": \"Hello from Till.\", " +
                "  \"questions\" : [{ " +
                "    \"text\": \"Do you have a few moments to answer a question or two?\", " +
                "    \"tag\": \"have_a_few_moments\", " +
                "    \"responses\": [\"Yes\", \"No\"], " +
                "    \"conclude_on\": \"No\", " +
                "    \"webhook\": \"https://yourapp.com/have_a_few_moments_results/\" " +
                "  }, " +
                "  { " +
                "    \"text\": \"What is your favorite color?\", " +
                "    \"tag\": \"favorite_color\", " +
                "    \"responses\": [\"Red\", \"Green\", \"Yellow\"], " +
                "    \"webhook\": \"https://yourapp.com/favorite_color_results/\" " +
                "  }, " +
                "  { " +
                "    \"text\": \"Who is you favorite Star Wars character?\", " +
                "    \"tag\": \"favorite_star_wars_character\", " +
                "    \"webhook\": \"https://yourapp.com/favorite_star_wars_character_results/\" " +
                "  }], " +
                "  \"conclusion\": \"Thank you for your time\" " +
                "}"
            );
        } catch(Exception e) {
            System.out.println(e.toString());
        }
    }
}

Voice

curl -H "Content-Type: application/json" -X POST -d '{
  "phone": ["phone_number"],
  "method": "VOICE",
  "introduction": "Hello from Till.",
  "questions" : [{
    "text": "Do you have a few moments to answer a question or two?",
    "tag": "have_a_few_moments",
    "responses": ["Yes", "No"],
    "conclude_on": "No",
    "webhook": "https://yourapp.com/have_a_few_moments_results/"
  },
  {
    "text": "What is your favorite color?",
    "tag": "favorite_color",
    "responses": ["Red", "Green", "Yellow"],
    "webhook": "https://yourapp.com/favorite_color_results/"
  },
  {
    "text": "Who is you favorite Star Wars character?",
    "tag": "favorite_star_wars_character",
    "webhook": "https://yourapp.com/favorite_star_wars_character_results/"
  }],
  "conclusion": "Thank you for your time"
}' "https://platform.tillmobile.com/api/send?username=username&api_key=api_key"

On a successful send request a HTTP 200 will be returned with a JSON payload. The JSON payload contains resource URLs that can be used to track status and collected results.

{
  "project_launch_guid": "a45",
  "stats_url": "/api/stats/a45?username=username&api_key=api_key",
  "results_url": "/api/results?username=username&api_key=api_key&project_launch_guid=a45"
}

📘

Project launch

The project_launch_guid attribute is used to filter the results and stats APIs to a specific send request.

❗️

Max phone numbers per request

There is a maximum of 300 phone numbers for each send request.

Updated over 6 years ago

What’s Next