Rungopher API v1.3
Conversation Outputs (i.e. 'Results')
Any answer a user gives to a question (or information that they provide) is captured by Rungopher and able to be sent in real time to your system, or available for you to retrieve at any stage from our API.
Within the following documentation, we will refer to any piece of this captured data as 'result'. Below are the basic results that can be produced by Rungopher conversations:
boolean
Used for these result names: accepted, acceptedUpgrade, addressConfirmed, convertedToEmail, cancelled, optedOut
{
"campaignId": 15,
"campaignToken": "143-dfvsm-3r3ndkd",
"contactId": "1",
"id": 110,
"resultType": "boolean",
"resultName": "accepted",
"data": {
"answer": "yes"
},
"context": "Yes, that would be great, thanks!",
"timestamp": "2017-11-14T10:56:14Z"
}
email
Used for these result names: newEmail
{
"campaignId": 15,
"campaignToken": "143-dfvsm-3r3ndkd",
"contactId": "1",
"id": 111,
"resultType": "email",
"resultName": "newEmail",
"data": {
"email": "mark.hingston@rungopher.com"
},
"context": "Sure, please send to mark.hingston@rungopher.com thx!",
"timestamp": "2017-11-14T10:56:14Z"
}
phone
Used for these result names: newNumber
{
"campaignId": 15,
"campaignToken": "143-dfvsm-3r3ndkd",
"contactId": "1",
"id": 112,
"resultType": "phone",
"resultName": "newNumber",
"data": {
"phone": "+61400222111"
},
"context": "Actually I have a new number, it's 0400 222 111",
"timestamp": "2017-11-14T10:56:14Z"
}
address
Used for these result names: newAddress
{
"campaignId": 15,
"campaignToken": "143-dfvsm-3r3ndkd",
"contactId": "1",
"id": 113,
"resultType": "address",
"resultName": "newAddress",
"data": {
"city": "sydney",
"state": "NSW",
"postcode": "2000",
"streetAddress": "5/400 george street"
},
"context": "Ahhh, no it's 5/400 george street, sydney, nsw 2000",
"timestamp": "2017-11-14T10:56:14Z"
}
linkClicked
Used for these result names: linkClicked
{
"campaignId": 15,
"campaignToken": "143-dfvsm-3r3ndkd",
"contactId": "1",
"id": 114,
"resultType": "linkClicked",
"resultName": "linkClicked",
"data": {
"link": "https://www.mycompany.com/myevent",
"count": "1"
},
"timestamp": "2017-11-14T13:20:13Z"
}
N.B. If the contact clicks many times, multiple linkClicked events will be produced, with the count increased by one each time.
allSms
Used to send all of your inbound_sms and outbound_sms content
{
"campaignId": 16,
"campaignToken": "cd0c673d-a2ec-48df-b514-3a26e0f65254",
"contactId": "1",
"id": 115,
"resultType": "sms",
"resultName": "allSms",
"data": {
"kind": "inbound_sms",
"campaignName": "My Event RSVPs",
"content": "Great"
},
"timestamp": "2017-11-14T10:56:14Z"
}
Notes
- All timestamps are in ISO-8601 format.
- All
idvalues are globally unique.
Real Time
To get real time results, you will need to register a webhook url by mailing it to support@rungopher.com. When a conversation produces a result, such as a contact said "yes" to attend an event, you will be notified via a POST request to your webhook url. (To go live with your integration, your webhook url will need to be HTTPS)
Request (sent from RunGopher server -> your server)
POST to your registered webhook url:
{
"campaignId": 15,
"campaignToken": "143-dfvsm-3r3ndkd",
"contactId": "1",
"id": 110,
"resultType": "boolean",
"resultName": "accepted",
"data": {
"answer": "yes"
},
"context": "Yes, that would be great, thanks!",
"timestamp": "2017-11-14T10:56:14Z"
}
POSTs will be delivered to your webhook when the contact replies to a conversation. Note that there is no guarantee of the order in which result POSTs get delivered to your webhook.
Response (reply from your server -> RunGopher server)
You should return a 200 OK response once you have handled the incoming result. We will resend to your global webhook url once every 5 minutes until you return a 200 response code. All content of the response will be ignored.
Polling
There are a number of endpoints that return individual result data. For example, to retrieve all sms content, you'd send a GET request to this endpoint:
GET api/v1/results/allSms
Response:
[
{
"id":1,
"campaignId": 15,
"campaignToken":"token-1",
"contactId":"contact-40",
"resultType":"sms",
"resultName":"allSms",
"data":{
"content":"Hi, just wanted to let you know about our big sale coming up!",
"campaignName": "My Campaign",
"kind": "outbound_sms"
},
"timestamp":"2017-10-25T21:15:00Z"
},
{
"id":2,
"campaignId": 15,
"campaignToken":"token-1",
"contactId":"contact-40",
"resultType":"sms",
"resultName":"allSms",
"data":{
"content":"Thanks! I'll go check it out",
"campaignName": "My Campaign",
"kind": "inbound_sms"
},
"timestamp":"2017-10-25T23:15:00Z"
}
]
Filtering by time:
Each of the result endpoints returns a list of the relevant results. To limit data by time, you can give each of the above endpoints the after parameter. e.g. for everything since the beginning of July 13th, you'd use: 2017-07-13T00:00:00+10:00
With url encoding that looks like:
GET api/v1/results/allSms?after=2017-07-13T00:00:00%2B10:00
Then you will only receive results that happened after the timestamp you sent us.
The after timestamp needs to be in ISO-8601 format, but can be from any timezone. eg any of:
1970-01-01T00:00:00Z (the Z is a special way of indicating +00:00, ie. UTC)
1970-01-01T00:00:00+01:00
1970-01-01T00:00:00+10:00
1970-01-01T00:00:00+21:00
All Endpoints:
api/v1/results/allSms
api/v1/results/optedOut
api/v1/results/newAddress
api/v1/results/newEmail
api/v1/results/accepted
api/v1/results/emailConfirmed
api/v1/results/addressConfirmed
api/v1/results/acceptedUpgrade
api/v1/results/convertedToEmail
api/v1/results/cancelled
api/v1/results/newNumber
api/v1/results/linkClicked