Till

The Till Developer Hub

Welcome to the Till developer hub. You'll find comprehensive guides and documentation to help you start working with Till as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

/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.

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 2 years ago


/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.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.