Projects
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 aproject 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.
Updated about 7 years ago