The Web Hook allows you to configure TextIt to send new events to your application. Each time a new event occurs, TextIt will make a POST request to the URL you configure with the body of the POST containing details on the event. While developing your application you may want to use the simulator to test incoming events.

Delivery URL

For each channel you can configure a delivery URL that TextIt will POST incoming messages to. You can include URL parameters in this URL to help identify that the request is indeed coming from TextIt.

Event Types

The events that TextIt will send to your webhook is as follows. Note that this list may be expanded in the future so your web app should be tolerant to receiving new event types without causing errors.

mo_smsAn incoming message was received by the Android phone
mt_sentAn outgoing message has been confirmed as sent by the Android phone
mt_dlvdThe network has reported that an outgoing message was delivered to the final recipient
mo_missAn incoming call was missed on the Android phone
mo_callAn incoming call was picked up on the Android phone
mt_callAn outgoing call was made on the Android phone
mt_missAn outgoing call was made but never picked up by the recipient
alarmYour Android phone has either lost contact with TextIt or is reporting a very low battery
flowA user has reached an API action in one of your flows

Response Format

Your web service should return a 200 or 201 status code to mark acceptance of the event. If a 400 or 500 status code is returned then TextIt will retry delivering the event up to three times. You can view a log of recent events through your API Log when logged in.

Optionally, your web service can choose to respond to any event by returning a JSON response body using the same format as the Messages Endpoint. For example, your service could respond with the following JSON content to send a message to two contacts

{
    "phone": ["+250788123123", "+250788123124"],
    "text": "Walk into the club like, whattup, I have a big clock"
  }
  

Receiving SMS Messages

Say you set your webhook URL to http://www.yourapp.com/app.php?password=akabanga. If your Android phone receives the text message "Im gonna pop some tags" from "+250788123132" then TextIt will POST the following:

POST http://www.yourapp.com/app.php?password=akabanga
  event=mo_sms&id=23554&channel=254&channel_phone=%2B250788111111&phone=%2B250788123123&text=Im+gonna+pop+some+tags&time=2013-01-01T05:34:34.034
  
eventmo_sms
relayerThe id of the channel that received this message
relayer_phoneThe phone number of the channel that received this message
smsThe id of this message
phoneThe E164 phone number of the sender of this message
textThe text of the message, note that this may be longer than 160 characters as TextIt will combine multipart messages
statusThe current status of this message, one of Q,S,D,E or F
directionThe direction of the message, either I for incoming or O for outgoing
timeThe date and time that this message was received by the Android phone

Sent and Delivery Reports

When you send messages to the TextIt API you can also receive reports as to when your message was sent by your Android channel as well as when the message was delivered to the final recipient. (note that some messages may never receive delivery reports) The sent and delivered events will be represented by the mt_sent and mt_dlvd events.

Say you have sent the message "Only got $20 in my pocket" to "+250788383383". When your Android phone has successfully sent the message, you will notified with the following message:

POST http://www.yourapp.com/app.php?password=akabanga
  event=mt_sent&id=23555&relayer=254&relayer_phone=%2B250788111111&phone=%2B250788123123&text=Only+got+$20+in+my+pocket&time=2013-01-01T05:34:34.034
  
eventmt_sent or mt_dlvd
relayerThe id of the channel that sent this message
relayer_phoneThe phone number of the channel that sent this message
smsThe id of this message
phoneThe E164 phone number of the recipient of this message
textThe text of the message, note that this may be longer than 160 characters as TextIt will combine multipart messages
statusThe current status of this message, one of Q,S,D,E or F
directionThe direction of the message, either I for incoming or O for outgoing
timeThe date and time that this message was sent or delivered

Call Events

Although the TextIt Android application cannot place or receive calls, it does log all inbound and outbound calls. This is often used to record missed incoming calls and respond to them in some way. TextIt will send you these events as they occur, using the event types mo_miss, mo_call, mt_call and mt_miss.

Say your channel receives a missed call from "+250788383383", you will receive the following POST from TextIt:

POST http://www.yourapp.com/app.php?password=akabanga
  event=mo_miss&id=125156&relayer=254&relayer_phone=%2B250788111111&phone=%2B250788123123&time=2013-01-01T05:34:34.034&duration=0
  
eventOne of mo_miss, mo_call, mt_miss or mt_call
relayerThe id of the channel that received this call
relayer_phoneThe phone number of the channel that received this call
callThe id of this call
phoneThe E164 phone number of the caller or callee
timeThe date and time that this call took place
durationThe length in seconds that this call lasted, 0 for missed calls

Alarm Events

TextIt keeps track of the status of your channels to make sure they are connected to the network, charged and able to send text messages. In order to help you manage this state, TextIt can send you events when an alarm condition occurs on one of your channels.

Say that your channel hasn't contacted the TextIt service in over 30 minutes. We will POST the following to your webhook.

POST http://www.yourapp.com/app.php?password=akabanga
  event=alarm&relayer=254&relayer_phone=%2B250788111111&battery=50&last_seen=2013-01-01T05:35:32.012&unsent=4
  
eventalarm
relayerThe id of the channel that has a problem
relayer_phoneThe phone number of the channel that has a problem
power_levelThe battery level as of the channel as an int
power_statusOne of CHARGING or DISCHARGING
power_sourceThe source of power for the device
network_typeWhat type of network the device is connected to
pending_message_countHow many messages this channel still has unsent
retry_message_countHow many messages this channel is currently retrying after a send error
last_seenThe date and time that this channel last contacted the TextIt server

Flow Events

If you choose to have your webhook called when a user reaches a particular point in a flow, this is the resulting event. You will receive the phone number of the contact, flow name and their state in the flow.

Say that a user reaches an API node in a flow, we will POST the following to your webhook.

POST http://www.yourapp.com/app.php?password=akabanga
  event=flow&relayer=254&relayer_phone=%2B250788111111&phone=%2B250788123123&flow=1524&step=12341234-1234-1234-1234-1234-12341234&values=[]
  
eventflow
relayerThe id of the channel that is executing this flow
relayer_phoneThe phone number of the channel that is executing this flow
phoneThe phone number of the contact that has reached this point in the flow
flowThe id of the flow that received an event (use the URL on your flow page for reference)
flow_nameThe name of the flow that received an event
flow_base_languageThe base language of the flow that received an event
stepThe step that triggered this API call, use the flow step for reference
valuesThe values collected from the user so far through this flow, in order of collection time

The values parameter will be JSON encoded in the following format:

"values": [
    { "label": "Water Source", "category": "Stream", "text": "from stream", "value": "Stream", "time": "2013-01-01T05:35:32.012" },
    { "label": "Boil", "category": "Yes", "text": "yego", "value": "Yes", "time": "2013-01-01T05:36:54.012" },
    { "label": "Household Members", "category": "All", "value": "15", "text": "15", "time": "2013-01-01T05:58:32.012" }
  ]
  

labelThe label for the rule set
categoryHow the user's response was categorized
valueThe value that was parsed from the user's response, for example just the number in a numeric response"
textThe full text of the user's response
timeThe time that the user responded, in JSON format: 2013-01-01T05:34:34.034