Description

This service allows clients to access their TalkBox data through a web service API. Clients can perform basic operations on their contact database such as reading, adding and editing of contacts and fields. Where possible the API adheres to REST standards.

Structured response data is in JSON format.


Authentication

Authentication is done with Basic HTTP Authentication as defined by W3C.

username
A valid TalkBox user name (your login email).
password
An account specific web service key.

The authentication does not persist, each request authenticates independently. Authentication failure will return HTTP status code 401.


Resources

The API is accessed by the endpoint located at talkbox.impactapp.com.au/service/v1.

Resource Description
GET /account Returns a set of account properties and current statistics. No additional parameters required.
PUT /account Updates the specified account properties. Only certain properties can be updated in this fashion. See usage for details.
GET /fields Returns all contact fields. No additional parameters required.
POST /fields Creates a new field. Parameters are name, field_type and options (optional).
PUT /fields/:system_name Update the field specified by :system_name. name and options attributes may be changed.
A full set of desired options is required for each update. Any existing options not included in the options array will be destroyed.
GET /contact/:id Returns contact specified by :id. Contact is returned in JSON format.
POST /contact Creates a new contact. Parameters are contact field names as returned by the get fields resource.
PUT /contact/:id Update the contact specified by :id. Note that this does not fully replace the contact, just the attributes that have been passed in.
Options for multiple choice fields are added to those already present.
DELETE /contact/:id Delete the contact specified by :id
POST /contact/create_or_update Creates a new contact or updates existing contact if a duplicate is found in the database.
A duplicate is defined here as an email or mobile number match.
GET /contact/find_first Performs a simple search and returns the first match. Accepts two optional parameters; email and mobile_number.
POST /contact/authenticate Performs contact authentication. Accepts two parameters; email and password.
POST /contact/:id/password_reset_email Sends a password reset email to the contact.
GET /contact/:id/password_reset_email Returns reset_password_token for the contact.
(deprecated – use Tags instead)
GET /tags Returns all tags for the account.
GET /tags/:id Returns tag specified by :id. Tag is returned in JSON format.
POST /tags Create a new tag
PUT /tags/:id Update the tag specified by :id. The data passed in as parameter will override the existing data.
DELETE /tags/:id Delete the tag specified by :id.
(deprecated – use Contacts in Tags instead)
GET /tags/:id/contacts Returns all contacts in the tag specified by :id.
POST /tags/:id/contacts/:id Add a contact to a tag
DELETE /tags/:id/contacts/:id Delete a contact from a tag specified by :id.
GET /unsubscriptions Returns all unsubscriptions for the account.
POST /unsubscriptions Create a new unsubscription
POST /promotions Create a new email or SMS promotion
PUT /promotions/:id Update an existing promotion
DELETE /promotions/:id Delete an existing promotion
GET /communications Returns sent communication reports
GET /promotions/:id:communications Returns sent communication reports for a specific promotion
POST /promotions/:id/communications Trigger a communication from an API-triggered promotion
GET /email_sender_details Returns all email sender details. No additional parameters required.
POST /email_sender_details Creates a new email sender detail. Parameters are name, and address.
PUT /email_sender_details/:id Update the email sender detail specified by :id. name and address attributes may be changed.
DELETE /email_sender_details/:id Delete an email sender detail specified by :id.
GET /sms_sender_details Returns all sms sender details. No additional parameters required.
POST /sms_sender_details Creates a new sms sender detail. Parameters are name.
PUT /sms_sender_details/:id Update the sms sender detail specified by :id. name attributes may be changed.
DELETE /sms_sender_details/:id Delete a sms sender detail specified by :id.
GET /editor/block/session Gets a key for an editor session.
PUT /recipients Gets prospective recipient counts. Note that this is a PUT request rather than a GET request, because these calls readily generate query strings that are so large they cause HTTP 414 errors.

Usage


Account


Get

You can retrieve account information by issuing an HTTP GET request to /account.

If the get is successful you will be returned an object with the account's properties and most recent statistics as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/account
Example Response
        {
        "created_at": "2015-01-20T09:41:04+11:00",

        // Business contact details for ImpactData
        "name": "The Pub On The Corner",
        "contact_name": "Barry O'Manager",
        "email": "manager@tpotc.com.au",
        "address": "PO Box 4556, Brunswick",
        "phone": "0423 456 789",

        // Business contact details for customers
        "street_address": "Cnr. High Street and Low Road",
        "suburb": "Brunswick",
        "postcode": "3056",
        "state": "VIC",
        "country": "Australia",
        "website": "http://www.tpotc.com.au",
        "public_email": "bookings@tpotc.com.au",
        "public_phone": "03 9876 5432",

        "default_email_sender_detail_id": 123,
        "default_sms_sender_detail_id": 456,
        "auto_purchase_sms_credits_amount": 1000,
        "timezone": "Melbourne",
        "sms_credit_price_ex_tax": "$0.0750",

        // Account latest statistics
        "statistics_created_at": "2015-01-20T08:00:00+11:00",
        "last_login": 1,               // Days since last login
        "last_send": 5,                // Days since last send
        "contacts_count": 20431,
        "thirty_day_change": 512,      // Contacts joining the database in the last 30 days
        "eligible_email_count": 18457, // Contacts eligible to receive email
        "eligible_sms_count": 1275,    // Contacts eligible to receive SMS
        "facebook": true,              // Is the account connected to Facebook?
        "twitter": false,              // Is the account connected to Twitter?
        "forms": 3,                    // # of forms which the account is using
        "auto_comms": 2                // # of currently active automated communications
        }

Update

You can update the business contact details of the account by issuing an HTTP PUT request to /account with any of the following optional parameters:

Parameter Type Description
street_address string Street address of the business.
suburb string Suburb/town/etc. in which the business is located.
postcode string Post code of the business.
state string State/county/etc. in which the business is located.
country string Country in which the business is located.
website string The business's public website.
public_email string Address for contacts' email enquiries for the business.
public_phone string Phone number for contacts' phone enquiries for the business.

If the update is successful you will get the an object representing the updated account as per GET /account above.

Example Request
PUT https://talkbox.impactapp.com.au/service/v1/account
PUT Data website=www.cornerpub.com&public_email=bookings@cornerpub.com
Example Response
        {
          "created_at": "2015-01-20T09:41:04+11:00",
          "name": "The Pub On The Corner",
          "contact_name": "Barry O'Manager",
          "email": "manager@tpotc.com.au",
          "address": "PO Box 4556, Brunswick",
          "phone": "0423 456 789",

          "street_address": "Cnr. High Street and Low Road",
          "suburb": "Brunswick",
          "postcode": "3056",
          "state": "VIC",
          "country": "Australia",
          "website": "http://www.cornerpub.com",
          "public_email": "bookings@cornerpub.com",
          "public_phone": "03 9876 5432",

          "default_sender_detail_id": 123,
          "auto_purchase_sms_credits_amount": 1000,
          "timezone": "Melbourne",
          "sms_credit_price_ex_tax": "$0.0750",

          "statistics_created_at": "2015-01-20T08:00:00+11:00",
          "last_login": 1,
          "last_send": 5,
          "contacts_count": 20431,
          "thirty_day_change": 512,
          "eligible_email_count": 18457,
          "eligible_sms_count": 1275,
          "facebook": true,
          "twitter": false,
          "forms": 3,
          "auto_comms": 2
        }

Fields


Get

You can retrieve the list of fields by issuing an HTTP GET request to /fields.

If the get is successful you will be returned a list of fields, each with their :system_name containing the field details as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/fields
Example Response
      {
        "first_name":
        {
          "field_type":"Text",
          "options":{},
          "name":"First name"
        },
        "last_name":
        {
          "field_type":"Text",
          "options":{},
          "name":"Surname"
        },
        "favourite_marx_bro":
        {
          "field_type":"MultipleChoice",
          "options":
          {
            "11":"Harpo",
            "12":"Zeppo",
            "9":"Chico",
            "10":"Groucho"
          },
          "name":"Favourite Marx Brother"
        },
        "email":{
          "field_type":"Text",
          "options":{},
          "name":"Email"
        }
      }

Create

You can create a field by issuing an HTTP POST request to /fields with the following parameters:

Parameter Type Description
name string Required. Field name.
field_type string of 'Text', 'Boolean', 'SingleChoice', 'MultipleChoice', 'Number', 'Date' or 'Float'. See Field types. Required. Field type.
options array Field options (Accepted when field_type is 'SingleChoice' or 'MultipleChoice').

If the create is successful you will get the field :system_name containing the field details as a response.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/fields
POST Data name=A+choice+field&field_type=MultipleChoice&options=The+first+one,The+middle+one,The+last+one
Example Response
      {
        "a_choice_field":
          {
          "name":"A choice field",
          "field_type":"MultipleChoice",
          "options":
          {
            "51":"The first one",
            "52":"The middle one",
            "53":"The last one"
          }
        }
      }

Update

You can update a field by issuing an HTTP PUT request to /fields/:system_name with the following parameters:

Parameter Type Description
name string Required. Field name.
options array Field options (Accepted when field_type is 'SingleChoice' or 'MultipleChoice').

NOTE: While options are not required for updates to SingleChoice and MultipleChoice fields, if any options are included, the full set of desired options is then also required. Any existing options not included in the options array will be destroyed from within the application.

If the update is successful you will get the field :system_name containing the field details as a response.

Example Request
PUT https://talkbox.impactapp.com.au/service/v1/fields/a_choice_field
PUT Data name=Which+option+are+you+interested+in?&options=The+first+one,The+last+one,Another+one
Example Response
      {
        "a_choice_field":
          {
          "name":"Which option are you interested in?",
          "field_type":"MultipleChoice",
          "options":
          {
            "51":"The first one",
            "53":"The last one",
            "67":"Another one"
          }
        }
      }

Contacts

NOTE:Contacts require either a valid email address or mobile number to be saved to the database.

Existing contact attributes cannot be removed via the API, they may only be updated (or added to in the case of 'MultipleChoice' fields).

Passwords may be set for contacts by assigning the password attribute.

Certain attributes cannot be changed, including unreachable_email, unreachable_mobile and unsubscribed. The unsubscribed attribute may be set to true through the creation of a matching Unsubscription record.

Tags belonging to the contact are returned as part of a successful response along with contact attributes, but they can currently only be set via the Contacts in Tags endpoints


Get

You can retrieve the details of a contact by issuing an HTTP GET request to /contact/:id.

If the get is successful you will be returned the contact's details as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/contact/300
Example Response
      {
        "id": 300,
        "first_name": "Barry",
        "last_name": "Hall",
        "email": "barry.hall@gmail.com",
        "favourite_marx_bro": [9,10],
        "tags": ["VIP","Gaming"]
      }

Create

You can create a contact by issuing an HTTP POST request to /contact with the following parameters:

Parameter Type Description
email string Required (or provide mobile_number). Contact email address.
mobile_number string Required (or provide email). Contact mobile number.
Various additional contact data See Field types for acceptable data formats Contact attributes.
version_tags array Arbitrary strings to label the change. These are displayed with contact changes in TalkBox. Used for manual change autiting. e.g. ["mobile_app_v3"]

If the create is successful you will get the contact's details as a response.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/contact
POST Data first_name=Julia&last_name=Gillard&email=julia.gillard@pm.gov.au
Example Response
      {
        "id": 301,
        "first_name": "Julia",
        "last_name": "Gillard",
        "email": "julia.gillard@pm.gov.au",
        "favourite_marx_bro": [],
        "tags": []
      }

Update

You can update a contact by issuing an HTTP PUT request to /contact/:id with the following parameters:

Parameter Type Description
Various additional contact data See Field types for acceptable data formats Contact attributes.
version_tags array Arbitrary strings to label the change. These are displayed with contact changes in TalkBox. Used for manual change autiting. e.g. ["mobile_app_v3"]

If the update is successful you will get the contact's details as a response.

Example Request
PUT https://talkbox.impactapp.com.au/service/v1/contact/300
PUT Data email=big.barry@gmail.com&favourite_marx_bro=10,11
Example Response
      {
        "id": 300,
        "first_name": "Barry",
        "last_name": "Hall",
        "email": "big.barry@gmail.com",
        "favourite_marx_bro": [9,10,11],
        "tags": ["VIP","Gaming"]
      }

Delete

You can delete a contact by issuing an HTTP DELETE request to /contact/:id

Example Request
DELETE https://talkbox.impactapp.com.au/service/v1/contact/300
Example Response
      {
        "id": 300,
        "first_name": "Barry",
        "last_name": "Hall",
        "email": "big.barry@gmail.com",
        "favourite_marx_bro": [9,10,11],
        "tags": ["VIP","Gaming"],
        "deleted": true
      }
      


Create or Update

You can update an existing contact if a duplicate is found or create a new contact if one is not by issuing an HTTP POST request to /contact/create_or_update with the following parameters:

Parameter Type Description
email string Required (or provide mobile_number). Contact email address.
mobile_number string Required (or provide email). Contact mobile number.
Various additional contact data See Field types for acceptable data formats Contact attributes.

If the create or update is successful you will get the contact's details as a response.

NOTE: A duplicate is defined here as an email or mobile number match.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/contact/create_or_update
POST Data first_name=J&last_name=Gillard&email=julia.gillard@pm.gov.au&favourite_marx_bro=9,10
Example Response
      {
        "id": 301,
        "first_name": "J",
        "last_name": "Gillard",
        "email": "julia.gillard@pm.gov.au",
        "favourite_marx_bro": [9,10],
        "tags": []
      }

Find First

You can find the first contact that matches any text field, including email or mobile number, by sending a HTTP GET request to /contact/find_first with the following parameters:

Parameter Type Description
email string Contact email address.
mobile_number string Contact mobile number
< field_name > string Any arbitrary text field in the account (see fields)

If the get is successful you will be returned the found contact's details as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/contact/find_first
GET Data email=julia.gillard@pm.gov.au&first_name=Julia
Example Response
      {
        "id": 301,
        "first_name": "Julia",
        "last_name": "Gillard",
        "email": "julia.gillard@pm.gov.au",
        "favourite_marx_bro": [],
        "tags": []
      }

Authenticate contact

You can authenticate contact matching an email and password by sending a HTTP POST request to /contact/authenticate with the following parameters:

Parameter Type Description
email string Required. Contact email address.
password string Required. Contact password.

If the POST is successful you will be returned the found contact's details as a response.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/contact/authenticate
POST Data email=julia.gillard@pm.gov.au&password=exprimeminister
Example Response
      {
        "id": 301,
        "first_name": "Julia",
        "last_name": "Gillard",
        "email": "julia.gillard@pm.gov.au",
        "favourite_marx_bro": [],
        "tags": []
      }

Reset Password

You can request to reset password for a contact by sending a HTTP POST request to /contact/:id/password_reset_email . An email is triggered to go out to the contact's email with a link to reset the password. The link will contain parameter reset_password_token as the contact identifier.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/contact/101/password_reset_email
Example Response
      {
        'message'=>'success'
      }

Get Contact's Reset Password Token

You can request reset_password_token for a contact by sending a HTTP GET request to /contact/:id/password_reset_email.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/contact/101/password_reset_email
Example Response
        {
          "password_reset_email": "7vqwxZ4QHNcE8zJconKX"
        }

Update Contact Password

You can update contact password using a HTTP PUT request to /contact/:id with the following parameters:

Parameter Type Description
password string Required. Contact new password. Minimum length of 6 characters.
password_confirmation string Required. Contact new password confirmation.
Example Request
PUT https://talkbox.impactapp.com.au/service/v1/contact/301
PUT Data password=newpassword&password_confirmation=newpassword
Example Response
        {
          "id": 301,
          "first_name": "Julia",
          "last_name": "Gillard",
          "email": "julia.gillard@pm.gov.au",
          "favourite_marx_bro": [],
          "tags": []
        }


Segments


The use of the segments API is deprecated. Please use the Tags API instead


Tags

NOTE: Individual contacts' tags are also returned in the response of successful requests to the Contacts endpoints which return individual contacts.


Get

You can retrieve the list of tags by issuing an HTTP GET request to /tags.

If the get is successful you will be returned a list of tags as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/tags
Example Response
      [
        {
          "id": 38,
          "name": "Drinks Survey"
        },
        {
          "id": 51,
          "name": "Eligible for rides"
        }
      ]
      

You can retrieve the details of a tag by issuing an HTTP GET request to /tags/:id.

If the get is successful you will be returned the tag's details as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/tags/38
Example Response
      {
        "id": 38,
        "name": "Drinks Survey"
      }
      

Create

You can create a tag by issuing an HTTP POST request to /tags with the following parameters:

Parameter Type Description
name string Required. Tag name.
Example Request
POST https://talkbox.impactapp.com.au/service/v1/tags
POST Data name=new+tag+via+api
Example Response
      {
        "id": 63,
        "name": "New tag via api"
      }
      

Update

You can update a tag by issuing an HTTP PUT request to /tags/:id with the following parameters:

Parameter Type Description
name string Required. Tag name.

NOTE: Existing tag will be overwritten with the given data.

If the update is successful an updated tag is returned as a response.

Example Request
PUT https://talkbox.impactapp.com.au/service/v1/tags/50
PUT Data name=updated+tag+via+api
Example Response
      {
        "id": 50,
        "name": "updated tag via api"
      }
      

Delete

You can delete a tag by issuing an HTTP DELETE request to /tags/:id

Example Request
DELETE https://talkbox.impactapp.com.au/service/v1/tags/50
Example Response
      {
        "id": 52
        "name": "Does not exist any more",
        "deleted": true
      }
      

Contacts in Segments


The use of the segments contacts API is deprecated. Please use the Contacts in Tags API instead


Contacts in Tags


Get

You can retrieve the list of contacts in a tag by issuing an HTTP GET request to /tags/:id/contacts.

If the get is successful you will be returned a list of contacts, each with their :id as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/tags/1/contacts
Example Response
      {
        "id": [23,46,78,54]
      }
      

Create

You can add contacts to a tag by issuing an HTTP POST request to /tags/:id/contacts/:id

If the request is successful you will get a response with an empty body and an HTTP 200 code.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/tags/1/contacts/24
Example Response

      

Delete

You can remove a contact from a tag by issuing an HTTP DELETE request to /tags/:id/contacts/:id

If the request is successful you will get a response with an empty body and an HTTP 200 code.

Example Request
DELETE https://talkbox.impactapp.com.au/service/v1/tags/1/contacts/24
Example Response

      

Unsubscriptions

NOTE:

You are not able to delete unsubscriptions, only querying for and creation of unsubscriptions are allowed.

If an unsubscription matches a contact, the contact id will be returned as part of the response.


Get

You can retrieve the list of unsubscriptions by issuing an HTTP GET request to /unsubscriptions.

If the get is successful you will be returned a list of unsubscriptions as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/unsubscriptions
Example Response
      [
        {
          "channel": "mobile",
          "contact_info": "61412345678",
          "contact_id": 99999,
          "source": "app"
        },
        {
          "channel": "email",
          "contact_info": "no-email-please@outlook.com",
          "contact_id": null,
          "source": "api"
        }
      ]
      

Create

You can create an unsubscription by issuing an HTTP POST request to /unsubscriptions with the following parameters:

Parameter Type Description
channel string of 'email', or 'mobile'. Required. Channel type.
contact_info string Required. Contact information.
Example Request
POST https://talkbox.impactapp.com.au/service/v1/unsubscriptions
POST Data channel=email&contact_info=j.doe@gmail.com
Example Response
      {
        "channel": "email",
        "contact_info": "j.doe@gmail.com",
        "contact_id": null,
        "source": "api"
      }
      


Promotions


Create

You can create an email and/or SMS promotion which will send to a specified set of contacts by issuing an HTTP POST request to /promotions with the following parameters:

Parameter Type Description
name string At least one of name, email_subject, or sms_body is required. Promotion name and, in the case where email_subject is blank, the email's subject line.
email_subject string At least one of name, email_subject, or sms_body is required. Email subject and, in the case where name is blank, the promotion's name.
sms_body string At least one of name, email_subject, or sms_body is required. SMS body and, in the case where name and email_subject are blank, the promotion's name.
email_sender_detail_id integer Optional. The ID of the email sender detail representing the sender of the promotion. If omitted, the nominated default sender will be used, or the first sender if none is nominated. If an existing email_sender_detail_id is not known, email_sender_name and email_sender_address can be provided to find or create one.
email_sender_name string Optional. The displayed name of the sender of this email.
email_sender_address string Optional. The displayed address of the sender of this email.
sms_sender_detail_id integer Optional. The ID of the sms sender detail representing the sender of the promotion. If omitted, the nominated default sender will be used, or the first sender if none is nominated. If an existing sms_sender_detail_id is not known, sms_sender_name can be provided to find or create one.
sms_sender_name string Optional. The displayed name of the sender of this SMS.
raw_html string Either raw_html or structure required where the promotion has an email. Flyer content in raw html including <html> </html> tags.
structure string Either raw_html or structure required where the promotion has an email. Flyer content in the form of a JSON string as generated by the TalkBox drag and drop editor.
preferred_channel string. Either 'email' or 'sms' Optional. When a promotion has both an email and SMS component, determines whether the promotion will be sent to contacts who are reachable by both SMS and email. If email, it will send them an email only, if sms, it will send SMS only, otherwise, it will send them both an email and an SMS.
test boolean true or false Optional. If true, a communication arising from this promotion will be marked as test for reporting purposes (n.b. this only applies to communications created immediately - scheduled promotions will not be marked as tests).
Recipient Selection (use at most one of these)
filter_criteria string[][] An ordered array of hashes, each hash containing logical_operator (optional), field_name, operator and value, representing a set of criteria with which to filter recipients, e.g. filter_criteria[0][logical_operator]=AND&filter_criteria[0][field_name]=age&filter_criteria[0][operator]=%3C&filter_criteria[0][value]=30
recipient_details string Specific email addresses to send to.
tags string Comma separated list of tags to send to.
Schedule Selection (use at most one of these. If all are omitted, the promotion is to be sent immediately.)
send_time string of the form yyyy-mm-dd hh:mm Optional. Date and time to send the promotion.
date_trigger string[]

Optional. Hash containing field, hour, minute, offset_value, offset_period, offset_tense and only_nth_anniversary.

offset_value, offset_period and offset_tense will be combined into a string called offset, in the form of 3 days away.

Date-triggered promotions are sent every day at the local time given by hour and minute, searching for all contacts who's field is offset from the current send date.

If only_nth_anniversary is not provided, it will send each year on the anniversary of field. To send only once, specify a only_nth_anniversary value of 0.

If any of the recipient selection parameters are provided (filter_criteria, recipient_details, tags), each day's sends will be further restricted to contacts matching those parameters. This allows you to ie. set up segmented date-triggered messages on the same schedule.

Examples:
date_trigger[field]=next_appointment
date_trigger[offset_value]=3
date_trigger[offset_period]=days
date_trigger[offset_tense]=away
date_trigger[hour]=15
date_trigger[minute]=50
date_trigger[only_nth_anniversary]=0
Send the message at 3:50pm every day to any contact who's next appointment is currently 3 days away
date_trigger[field]=last_visit
date_trigger[offset_value]=1
date_trigger[offset_period]=month
date_trigger[offset_tense]=ago
date_trigger[hour]=13
date_trigger[minute]=0
date_trigger[only_nth_anniversary]=0 tags=Inner-city
Send the message at 1pm every day to any contact who's last visit is currently 1 month ago and are tagged with 'Inner-city'
date_trigger[field]=date_of_birth
date_trigger[offset_value]=2
date_trigger[offset_period]=weeks
date_trigger[offset_tense]=away
date_trigger[hour]=10
date_trigger[minute]=0
date_trigger[only_nth_anniversary]=21
Send the message at 10am every day to any contact who's 21st birthday is currently 2 weeks away
date_trigger[field]=date_of_birth
date_trigger[offset_value]=2
date_trigger[offset_period]=weeks
date_trigger[offset_tense]=away
date_trigger[hour]=10
date_trigger[minute]=0
Send the message at 10am every day to any contact who's birthday (of any age) is currently 2 weeks away

NOTE:

The email will be sent:
  • to all contacts in your database that are able to be sent an email unless you provide filter_criteria, recipient_details or tags
  • immediately unless you provide a send_time or date_trigger
Example Request
POST https://talkbox.impactapp.com.au/service/v1/promotions
POST Data
name=What's on this week&content=<!DOCTYPE html>
            <html><body><h1>A heading</h1><a href="www.google.com">Google it!</a>
            <img src="http://an-image.jpg"><p>A paragraph.</p>
            </body></html>&recipient_details=john.doe@gmail.com,jane.doe@gmail.com&send_time=2014-12-11 12:34
Example Response
      {
        "id": 123,
        "name": "What's on this week",
        "recipient_count": 10,
        "email_recipients": 10,
        "sms_recipients": 10,
        "send_time": "2014-12-11T12:34:00Z",
        "date_trigger": null
      }
      


Update

You can update a promotion by issuing an HTTP PUT request to /promotions/:id with the same parameters as creating a promotion.

NOTE: if send_time or date_trigger is omitted, the promotion will not be sent immediately, unlike creating a promotion.

Example Request
PUT https://talkbox.impactapp.com.au/service/v1/promotions/123
PUT Data sms_body=Rescheduling this promotion&send_time=2015-10-21 07:28
Example Response
      {
        "id": 123,
        "name": "Rescheduling this promotion",
        "recipient_count": 10,
        "email_recipients": 10,
        "sms_recipients": 10,
        "send_time": "2015-10-21T07:28:00Z",
        "date_trigger": null
      }
      

Delete

You can delete a promotion by issuing an HTTP DELETE request to /promotions/:id

Example Request
DELETE https://talkbox.impactapp.com.au/service/v1/promotions/123
Example Response
      {
        "id": 123,
        "name": "What's on this week",
        "recipient_count": 10,
        "email_recipients": 10,
        "sms_recipients": 10,
        "send_time": "2014-12-11T12:34:00Z",
        "date_trigger": null
      }
      

Communications


Get

You can retrieve the list of communications sent from an account by issuing an HTTP GET request to /communications.

If the get is successful, an array of summary details for each communication is returned, with 10 entries per page. Additional pages of results can be obtained with the ?page= parameter.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/communications
Example Response
      [
        {
          "id": 10567123,
          "name": "Friday Night Funk",
          "promotion_id": 10023789,
          "send_time": "2015-01-16T12:52:45+11:00",
          "channels": ["Email", "Sms"],
          "email_recipients": 1256,
          "email_opens": 332,
          "email_bounces": 5,
          "email_clicks": 100, // number of recipients who click at least one link
          "sms_recipients": 505,
          "flyer_url": "sbx.cc/fl73r",
          "thumbnail_url": "https://s3.amazonaws.com/assets.impactapp.com.au/web_thumbnails/flyer/374084/1425958840.png"
        },
        {
          "id": 10567456,
          "name": "Saturday Night Soul",
          "promotion_id": 10024725,
          "send_time": "2015-01-19T17:30:00+11:00",
          "channels": ["Sms"],
          "sms_recipients": 976,
          "thumbnail_url": null // thumbnails can take a short time to generate, and may be missing
        }
      ]

Get for Promotion

You can retrieve the list of communications created from a given promotion by issuing an HTTP GET request to /promotions/:id/communications.

If the get is successful, an array of summary details for each communication is returned, with 10 entries per page. Additional pages of results can be obtained with the ?page= parameter.

Parameter Type Description
page integer Optional. Defaults to 1. The page of results to return.
Example Request
GET https://talkbox.impactapp.com.au/service/v1/promotions/10023789/communications
Example Response
      [
        {
          "id": 10567890,
          "name": "Friday Night Funk",
          "promotion_id": 10023789,
          "send_time": "2015-01-16T12:52:45+11:00",
          "channels": ["Email", "Sms"],
          "email_recipients": 1256,
          "email_opens": 332,
          "email_bounces": 5,
          "email_clicks": 100, // number of recipients who click at least one link
          "sms_recipients": 505,
          "flyer_url": "sbx.cc/fl73r",
          "thumbnail_url": "https://s3.amazonaws.com/assets.impactapp.com.au/web_thumbnails/flyer/374084/1425958840.png"
        },
      ]

Create

You can trigger a communication to specific contacts from a saved API-triggered promotion by issuing an HTTP POST request to /promotions/:id/communications with the following parameters:

Parameter Type Description
contact_ids string Either contact_ids or recipient_details required. Comma-seperated list of contact IDs to send to.
recipient_details string Either contact_ids or recipient_details required. Comma-seperated list of email addresses to send to.
test boolean If true, recipient_details is required. Marks the send as a test for reporting purposes.

You can create and edit API-triggered messages in TalkBox from Communicate - Automated - API-Triggered.

Send reports and history for API-triggered sends can be found under the same page.

If the request is successful you will receive the created communication data in the response.

NOTE:

API-triggered promotions must be set to active. If an API-triggered promotion is disabled, the request will fail and no communication will be created.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/promotions/10123456/communications
POST Data contact_ids=9591062,9591063,9591065
Example Response
      {
        "id": 10567890,
        "name": "API-Triggered",
        "promotion_id": 10123456,
        "send_time": "2015-01-16T12:52:45+11:00",
        "channels": ["Email", "Sms"],
        "email_recipients": 0, // recipients can take a short period to generate, query using 'GET /communications/:id' for live data
        "email_opens": 0,
        "email_bounces": 0,
        "email_clicks": 0,
        "sms_recipients": 0,
        "flyer_url": "sbx.cc/fl73r",
        "thumbnail_url": "https://s3.amazonaws.com/assets.impactapp.com.au/web_thumbnails/flyer/374084/1425958840.png"
      }
      


Email Sender Details


Get

You can retrieve the list of email sender details by issuing an HTTP GET request to /email_sender_details.

If the get is successful you will be returned a list of email sender details as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/email_sender_details
Example Response
       [
         {
           "id": 123,
           "name": "The Pub On The Corner",
           "address": "marketing@cornerpub.com"
         },
         {
           "id": 456,
           "name": "Bands At The Pub On The Corner",
           "address": "bands@cornerpub.com"
         },
       ]

Create

You can create an email sender detail by issuing an HTTP POST request to /email_sender_details with the following parameters:

Parameter Type Description
name string Required. Name of email sender.
address string Required. Email address of sender. Must be a valid email address.

If the create is successful you will get the newly created email sender detail as a response.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/email_sender_details
POST Data name=The+Restaurant+At+The+Pub+On+The+Corner&address=restaurant@cornerpub.com
Example Response
       {
         "id": 789,
         "name": "The Restaurant At The Pub On The Corner",
         "address": "restaurant@cornerpub.com"
       }

Update

You can update an email sender detail by issuing an HTTP PUT request to /email_sender_details/:id with the following parameters:

Parameter Type Description
name string Required. Name of email sender.
address string Required. Email address of sender. Must be a valid email address.
Example Request
PUT https://talkbox.impactapp.com.au/service/v1/fields/email_sender_details/789
PUT Data name=The+Bistro+At+The+Pub+On+The+Corner&address=bistro@cornerpub.com
Example Response
       {
         "id": 789,
         "name": "The Bistro At The Pub On The Corner",
         "address": "bistro@cornerpub.com"
       }

Delete

You can delete an email sender detail by issuing an HTTP DELETE request to /email_sender_details/:id

Example Request
DELETE https://talkbox.impactapp.com.au/service/v1/email_sender_details/789
Example Response
        {
          "id": 789,
          "name": "The Bistro At The Pub On The Corner",
          "address": "bistro@cornerpub.com"
        }


Sms Sender Details


Get

You can retrieve the list of sms sender details by issuing an HTTP GET request to /sms_sender_details.

If the get is successful you will be returned a list of sms sender details as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/sms_sender_details
Example Response
       [
         {
           "id": 123,
           "name": "CornerPub",
         },
         {
           "id": 456,
           "name": "YourLocal",
         },
       ]

Create

You can create a sms sender detail by issuing an HTTP POST request to /sms_sender_details with the following parameters:

Parameter Type Description
name string Required. Name of sms sender. Must be alphanumeric or underscores and 11 characters or less. (No spaces, other symbols or non-ASCII characters. Underscores are allowed.)

If the create is successful you will get the newly created s,s sender detail as a response.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/sms_sender_details
POST Data name=CornerPub
Example Response
       {
         "id": 789,
         "name": "CornerPub",
       }

Update

You can update a sms sender detail by issuing an HTTP PUT request to /sms_sender_details/:id with the following parameters:

Parameter Type Description
name string Required. Name of sms sender. Must be alphanumeric or underscores and 11 characters or less. (No spaces, other symbols or non-ASCII characters. Underscores are allowed.)
Example Request
PUT https://talkbox.impactapp.com.au/service/v1/fields/sms_sender_details/789
PUT Data name=CornerPub
Example Response
       {
         "id": 789,
         "name": "CornerPub",
       }

Delete

You can delete a sms sender detail by issuing an HTTP DELETE request to /sms_sender_details/:id

Example Request
DELETE https://talkbox.impactapp.com.au/service/v1/sms_sender_details/789
Example Response
        {
          "id": 789,
          "name": "CornerPub",
        }


Editor


Get

You can establish a drag and drop (block) editor session by issuing an HTTP GET request to /editors/block/session.

If the get is successful a session key will be returned with which to access the editor at /editors/block. It is expected that the key will be used immediately, but it will be valid for access to the editor for up to 5 minutes from the moment of issue.

The parameters to this call are mostly URLs for an app or apps which are expected to work with TalkBox in supplying certain data necessary for the editor and receiving data when the editor session is concluded. At a minimum, the app or apps are expected to be able to receive the JSON structure which the editor generates. They may optionally also store autosave data, serve a set of templates for the editor to use, and manage metadata for images uploaded to the editor.

Modern browsers subject this kind of cross-domain communication (i.e. between TalkBox and other apps) to security restrictions. In order that the app or apps may communicate with TalkBox without restrictions, the app or apps must implement Cross-origin resource sharing, or CORS, allowing themselves to receive PUT, POST and GET calls from the origin URLs used by TalkBox. An example of a CORS setup giving TalkBox all required access to a Ruby on Rails app can be found here.

Parameter Type Description
callback_method "PUT" or "POST" Optional. Defaults to "POST". The HTTP method with which to call callback_url.
callback_url string Required. URL to which to PUT or POST the results of the editor session (see callback_method). It should expect to receive the parameter structure, which will be in the form of a JSON string.
exit_url string URL to which to navigate if the user wishes to exit the editor session without saving. If present, a link to the URL will be present in the form of a button labelled "Exit without saving".
images_url string URL from which to GET a list of images. It should return an array of JSON objects, each of which should have a name, url, and a guid, or globally unique identifier. It is expected but not required that those images saved by posting to image_url will be returned by this call.
image_url string This should contain the string "{guid}". When this is substituted for a GUID (globally unique identifier), it should yield a URL which should accept a PUT request containing data for the corresponding image. The following fields may be included when calling back to this URL - the guid itself, url (the location of the image file), height and width (in pixels) and a md5 hash for the image. It is expected but not required that the metadata for these images be stored and served back from images_url.
structure_url string Required if templates_url is absent.URL from which to retrieve the initial structure to be edited, if any. It should respond to a GET request with a JSON structure object as created by a previous editor session.
template_tags_url string URL from which to GET a list of template tags. It should return an array of either one or two arrays of JSON objects, each of which should have an id and a name. Each id should be able to be combined with templates_url as described below, under templates_url.
templates_url string Required if structure_url is absent. URL from which to GET a list of templates. It should return an array of JSON objects, each of which should have an id, name, structure object (as created by a previous editor session), and an optional thumbnail_url, ideally pointing to a 100 x 100 pixel image.
If template_tags_url is present, templates_url should contain the string "{tag_id}". When this is substituted for a given tag ID, it should yield a URL which should return data for the set of templates belonging to that that tag. e.g. if templates_url is "/templates/{tag_id}", and the tag ID is "special_events", then hitting /templates/special_events should return the set of templates tagged as "special_events".
versions_url string URL from which to GET a list of saved updates to a given structure. It should return an array of JSON objects, each of which should have a name and a url. The name will be used as the label on which a user clicks to retrieve the relevant version, and url is a URL from which to GET the structure corresponding to that version. As with structure_url, the URL should respond to to a GET request with a JSON structure object as created by a previous editor session. The expected workflow is that those versions will be both those auto-saved by having been posted to version_url (if available), and those saved by posting to callback_url.
version_url string URL to which to POST regular autosave updates to the structure being edited. As with callback_url, it should expect to receive the parameter structure, which will be in the form of a JSON string. See also version_url.
save_buttons JSON Optional array of hashes, each describing the name, text, and optional class for a custom save button. Custom save buttons will be shown next to the "Keep editing" and "Save and finish" buttons in the top bar after previewing. When a custom save button is clicked, the form is submitted to callback_url, with an extra parameter named after the button.
By default, class is unset, which displays the button in blue (matching the "Keep editing" button). If "primary" is provided, the button will be displayed in orange (matching the "Save and finish" button).
Example: [ {"name": "my_button", "class": "primary", "text": "My Button"} ]
Example Request
GET https://talkbox.impactapp.com.au/service/v1/editors/block/session
GET Data callback_url=http://example.com/documents/templates_url=http://example.com/tags/:tag_id/templates.json
Example Response
2--eyJhY2NvdW50X2lkIjoyLCJleHBpcmVzX2F0IjoiMjAxNS0wMS0yMlQwNTowODozMFoifQ==--2df3e71e2a8162132a66ea3b20cf59b2bb2e9131

Recipients


Prospective counts

You can get prospective recipient counts for a send by making a HTTP GET request to /recipients. You can optionally provide any of sms_body, filter_criteria or preferred_channel, all of which will be considered when calculating the prospective recipients. The data returned is the recipient counts for the given criteria if it was sent now.

Parameter Type Description
sms_body string Optional. If provided, the SMS part count estimates will use this as a base, giving correct part counts for multipart SMS or SMS with merge fields in it.
filter_criteria string[][] Optional. See here.
preferred_channel string. Either 'email' or 'sms' Optional. If a contact is reachable by both SMS and email, only consider them for this channel when estimating. If preferred_channel=email, and the contact has both email and SMS, they will not be included in the SMS estimates. If preferred_channel=sms, and the contact has both email and SMS, they will not be included in the email estimates.
Example Request
PUT https://talkbox.impactapp.com.au/service/v1/recipients
GET Data ?sms_body=Hello [first_name]!&filter_criteria[0][logical_operator]=AND&filter_criteria[0][field_name]=age&filter_criteria[0][operator]=%3C&filter_criteria[0][value]=30&preferred_channel=sms
Example Response
{
        "total": 5,
        "email": 5,
        "sms": 2,
        "both": 2,
        "sms_cost": "0.16",
        "sms_parts": 2
    }

Templates


Get

You can retrieve the list of account-specific templates by issuing an HTTP GET request to /templates.

If the get is successful you will be returned a list of templates as a response.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/templates
Example Response
      [
        {
          "id": 1067046281,
          "name": "My account-specific template",
          "structure": "{\r\n ... \r\n}",
          "enabled": true
        },
        {
          "id": 1067046282,
          "name": "Custom template",
          "structure": "{\r\n ... \r\n}",
          "enabled": true
        }
      ]

Show

You can retrieve data for a single account-specific templates by issuing an HTTP GET request to /templates/:id.

If the get is successful you will be returned the data for that template.

Example Request
GET https://talkbox.impactapp.com.au/service/v1/templates/12345
Example Response
        {
          "id": 12345,
          "name": "My account-specific template",
          "structure": "{\r\n ... \r\n}",
          "enabled": true
        }
      

Create

You can create an account-specific template by issuing an HTTP POST request to /templates with the following parameters:

Parameter Type Description
template[name] string Required. Name of template, shown in template picker.
template[structure] string Required. JSON string describing the structure of the template.
template[enabled] boolean Required. Whether the template is enabled (shown in template picker) or disabled (hidden from template picker).

If the create is successful you will get the newly created template as a response.

Example Request
POST https://talkbox.impactapp.com.au/service/v1/templates
POST Data template[name]=New Template&template[structure]={...}&template[enabled]=true
Example Response
      {
        "id": 12345,
        "name": "New template",
        "structure": "{...}",
        "enabled": true
      }

Update

You can update an account-specific template by issuing an HTTP PUT request to /templates/:id with the following parameters:

Parameter Type Description
template[name] string Required. Name of template, shown in template picker.
template[structure] string Required. JSON string describing the structure of the template.
template[enabled] boolean Required. Whether the template is enabled (shown in template picker) or disabled (hidden from template picker).
Example Request
PUT https://talkbox.impactapp.com.au/service/v1/fields/templates/12345
PUT Data template[name]=Updated Template&template[structure]={...}&template[enabled]=true
Example Response
      {
        "id": 12345,
        "name": "Updated Template",
        "structure": "{...}",
        "enabled": true
      }

Delete

You can delete an account-specific template by issuing an HTTP DELETE request to /templates/:id

Example Request
DELETE https://talkbox.impactapp.com.au/service/v1/templates/12345
Example Response
      {
        "id": 12345,
        "name": "Updated Template",
        "structure": "{...}",
        "enabled": true
      }



Data formats


Notes

The preferred format of posting any array data is by separating the input values by commas. Posting array data in other forms may result in unknown consequences.

Example
array=element1,element1,element3

Field types

These are the different data types handled in the application for both fields and contacts:

Data Type Format (for contact attributes) Created/Updated by /fields
Boolean true or false. Pass these in as strings ("true" or "false") or the integers 0 or 1. yes
Date A string of the form dd/mm/yyyy yes
Float (Decimal) A floating point number of the form 123.456 yes
Number An integer yes
MobileNumber A string containing a mobile number in full international format. no
Text A string yes
SingleChoice An option id integer yes
MultipleChoice An array of option ids is of the form 10,20,30 yes

JSON `structure` strings

Promotions, editors and templates expect their structure values to be a JSON string describing the document structure. These are not intended to be created or edited by hand, but are emitted by various API methods. These structure strings can be posted back to the TalkBox API anywhere an argument named structure is used.

Although these are not intended to be edited outside of TalkBox, below is an example JSON structure string that can be used for testing and verification.

    {
      "version": 1,
      "document": {
        "block_type": "Global",
        "background_colour": "rgb(255, 255, 255)",
        "origin": {
          "template_id": 4,
          "name": "Left-hand column w/header",
          "editable": false,
          "loaded_at": "2016-01-04T02:02:26.835Z"
        },
        "layout": {
          "layout": [
            [
              {
                "id": "r0c0",
                "width": 600,
                "default_blocks": [
                  "Heading"
                ]
              }
            ],
            [
              {
                "id": "r1c0",
                "width": 200,
                "default_blocks": [
                  "Text"
                ]
              },
              {
                "id": "r1c1",
                "width": 400,
                "default_blocks": [
                  "Image",
                  "Text"
                ]
              }
            ]
          ]
        },
        "font": "Arial",
        "dimensions": {
          "width": 600,
          "height": 97
        },
        "page_colour": "rgb(241, 241, 241)",
        "text_colour": "rgb(44, 53, 57)",
        "responsive": true,
        "allow_responsive": true,
        "padding_top": 10,
        "padding_bottom": 10,
        "padding_left": 10,
        "padding_right": 10,
        "read_only": false,
        "block_guid": "editor_layout"
      },
      "regions": {
        "r0c0": {
          "blocks": [
            {
              "block_type": "Heading",
              "html": "<div style=\"text-align: center; font-size: 36px; font-family: Arial; font-weight: bold;\">Heading</div>",
              "padding_top": 10,
              "padding_bottom": 10,
              "padding_left": 10,
              "padding_right": 10,
              "read_only": false,
              "block_guid": "adf05e26-74f7-4238-b9e1-c74e3d1a2305"
            }
          ]
        },
        "r1c0": {
          "blocks": [
            {
              "block_type": "Text",
              "html": "Left column text",
              "padding_top": 10,
              "padding_bottom": 10,
              "padding_left": 10,
              "padding_right": 10,
              "read_only": false,
              "block_guid": "2850fda6-9df7-4b94-9683-f0804d03d929"
            }
          ]
        },
        "r1c1": {
          "blocks": [
            {
              "block_type": "Text",
              "html": "Right column text",
              "padding_top": 10,
              "padding_bottom": 10,
              "padding_left": 10,
              "padding_right": 10,
              "read_only": false,
              "block_guid": "9a886c8d-5431-40f0-b1ae-2cd1eee70f06"
            }
          ]
        }
      }
    }
      

Errors

Standard HTTP status codes are used to indicate errors. There will usually be some additional information passed back in the body of the response.
In the case of 400 and 422 responses the body will contain one of the errors defined in the Custom Errors section below.


Code Error
400 Bad Request
401 Unauthorized, authentication failed
403 Forbidden, access is denied to this resource
404 Resource Not Found, check your url
422 Unprocessable Entity, possible validation errors
500 Server Error
505 Invalid email or password
506 Invalid reset password token

Requests that have been handled successfully return status code 200.


Custom Errors

These are passed back in the body of the response to provide additional information about some client errors (400, 422).
The errors are passed back as a two element JSON string of the form:

        {
          "code": 120,
          "description": "Email address is invalid"
        }

Code Error
110 Unknown Field/Attribute
120 Validation Error