All forms of communication between Till and end users are encapsulated in what we refer to as a Project. Each Project contains messages, questions, and light business logic critical to your application. A project could be a simple alert or it could be a complex set of questions that send results back to an external URL.

A Project is created in the form of a JSON payload.

When a project JSON payload is combined with /api/send/ it is used to reach out to the passed list of phone numbers in the phone field.

📘
Project launch
Each successful execution of a project via send results in a project launch that can be used to retrieve corresponding results and/or stats.

Project - Message

The JSON below defines a project for rendering a single message to one or more users.

{
  "phone": ["phone_number"],
  "text" : "Hello Till!"
}

Project - Question(s)

The JSON below defines a project for asking one or more users a set of questions.

To give the user context an optional introduction message can be provided. This will be rendered before any of the questions. An optional conclusion message can also be provided to give the user closing instructions or a "Thank you".

Question results are sent to the provided webhook URL defined for each question and stored for later retrieval via the results API.

Two question styles are supported: Multiple choice and Freeform.

Multiple choice questions will validate responses from users against a 1 based index for the response e.g. 1 or the response itself e.g. Red in the example below.

Freeform questions are not validated.

Simple branching can be achieved by using the optional conclude_on attribute. When present the user's response to a question will be tested against it. If a match occurs all subsequent questions will be skipped and the conclusion (if present) rendered.

📘
Complete existing sessions?
Multiple requests to a participant will be queued to ensure proper order of delivery. If queuing is not desired pass the optional complete_existing_sessions attribute in the JSON below to complete existing sessions before sending.

{
  "tag": "example_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"],
    "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"
}

📘
Question Tags
The tag attribute within a question can be used to filter via the results API

📘
Project Tags
The tag attribute within a project can be used to filter via both the results and stats APIs

📘

Webhook Request

If a webhook value (Fully qualified URL) was provided each validated result received will be POST'd to it. Results can be retrieved via the results endpoint as well.

{
  "project_launch_guid": "445c481f-c19c-49e5-9e84-b96b1a5cae0f",
  "participant_guid": "585897f2-2c30-43f5-8f6b-7c243e8ac4b0",
  "participant_phone_number": "+15558675309",
  "question_guid": "685897f2-2c30-43f5-8f6b-7c243e8ac4b0",
  "question_tag": "favorite_color",
  "question_text": "Favorite color?",
  "result_guid": "885897f2-2c30-43f5-8f6b-7c243e8ac4b0",
  "result_timestamp": "2016-11-27T11:57:14.060474",
  "result_answer": "2",
  "result_response": "Green"
}

With project under your belt you are ready to combine it with the send API.