Rungopher API v1.3 - Examples
Create Campaign
Below are the steps to create a Convert To Email solution asking the user if they want to receive their bills via email.
List Templates
Start by listing the available templates:
curl https://portal.rungopher.com/api/v1/template --header 'ApiKey: <yourApiKey>'
Response:
[
{
"category": "General",
"costPerContact": 0.56,
"description": "This charity solution template encourages supporters to switch to email delivery for particular documents (annual statements, tickets etc). If they accept, it requests their email.",
"displayName": "Convert to email",
"name": "ConvertToEmail"
},
{
"category": "Marketing",
"costPerContact": 0.56,
"description": "This campaign template promotes an event and notifies any interested leads that you will call them, at a time suitable for them. Leads are transitioned to the provided email address. There is an alternative response for outside of business hours. Great for: Event Ticket Sales, PD Training Event Sales and Training Course registrations.",
"displayName": "Event Promotion",
"name": "EventPromotion"
},
...
]
Create Campaign
We looked through the available templates and decided we want to create a Convert to Email campaign. Let's do that:
curl -XPOST https://portal.rungopher.com/api/v1/campaign --header 'ApiKey: <yourApiKey>' --header 'Content-Type: application/json' -d '{
"name": "ConvertToEmail",
"title": "2017-04-18: Email Conversion",
"transitionEmail": "me@gmail.com"
}'
Response:
{
"campaignId": 15,
"campaignToken": "0257a297-d0dd-4c90-a2d6-3c61b19360b9",
"costPerContact": 0.56,
"costPerExtraSms": 0.04,
"costPerTransitionEmail": 0.05,
"smsContent": [
{
"content": "Hi {{firstName}}, it's <Amy> from <MyCompany> here. Thanks for all your support so far! I was wondering whether you'd be happy to receive your <statements> by email? It means you'll receive them faster and also lets your support dollar go further. Would this be ok? Thanks <Amy>",
"displayName": "A. Opt in to email",
"name": "smsOptInToEmail"
},
{
"content": "Hey {{firstName}}, it's <Amy> from <ACME Corp> again. Would you be ok to receive your <statements> via email?",
"displayName": "A. Opt in to email (Follow up)",
"name": "smsFollowUp"
},
...
],
"state": "draft",
"title": "2017-04-18: Email Conversion",
"transitionEmail": "me@gmail.com",
"requiredFields": [
"firstName",
"lastName",
"mobile",
"contactId"
]
}
Edit the copy
The campaign has been created. Let's edit the campaign copy to be more appropriate to our cause:
curl -XPOST https://portal.rungopher.com/api/v1/campaign/15 --header 'ApiKey: <yourApiKey>' --header 'Content-Type: application/json' -d '
{
"smsContent": [
{
"name": "smsOptInToEmail",
"content": "Hi {{firstName}}! Mark from RunGopher here. Thanks for all your support so far! I was wondering whether you would like to receive your invoices by email? They will arrive faster and we can save a few trees. Would this be ok? Thanks - Mark"
},
{
"name": "smsFollowUp",
"content": "Hey {{firstName}}, Mark from RunGopher again. Just wondering if you would be ok to receive your invoices by mail?"
}
]
}'
Response:
{
"campaignId": 15,
"campaignToken": "0257a297-d0dd-4c90-a2d6-3c61bf24c648",
"costPerContact": 0.56,
"costPerExtraSms": 0.04,
"costPerTransitionEmail": 0.05,
"smsContent": [
{
"content": "Hi {{firstName}}! Mark from RunGopher here. Thanks for all your support so far! I was wondering whether you would like to receive your invoices by email? They will arrive faster and we can save a few trees. Would this be ok? Thanks - Mark",
"displayName": "A. Opt in to email",
"name": "smsOptInToEmail"
},
{
"content": "Hey {{firstName}}, Mark from RunGopher again. Just wondering if you would be ok to receive your invoices by mail?",
"displayName": "A. Opt in to email (Follow up)",
"name": "smsFollowUp"
},
...
],
"state": "draft",
"title": "2017-04-18: Email Conversion",
"transitionEmail": "me@gmail.com",
"requiredFields": [
"firstName",
"lastName",
"mobile",
"contactId"
]
}
Success!
Upload contacts
Let's send a test message to our own phone, to test the campaign copy:
curl -XPOST https://portal.rungopher.com/api/v1/campaign/15/contact --header 'ApiKey: <yourApiKey>' --header 'Content-Type: application/json' -d '{
"mode": "test",
"contacts": [
{
"contactId": "1",
"firstName": "Mark",
"lastName": "Jones",
"mobile": "+61468403453"
}
]
}'
Response:
{
"warnings": [],
"started": 1
}
The response indicates that 1 contact has been successfully started, and you should receive an SMS on your phone. Reply as appropriate to test out the campaign copy / logic. If necessary, you can resend to 'test' contacts by uploading them again.
You can send to test contacts as many times as you like, until you get the copy right. However, once you send to a contact in 'live' mode, you will not be able to send to them again in the same campaign.
Once we're happy with the SMS content, let's start the campaign proper by uploading 100 'live' contacts:
curl -XPOST https://portal.rungopher.com/api/v1/campaign/0257a297-d0dd-4c90-a2d6-3c61b19360b9/contact --header 'ApiKey: <yourApiKey>' --header 'Content-Type: application/json' -d '{
"mode": "live",
"contacts": [
{
"contactId": "1",
"firstName": "Mark",
"lastName": "Jones",
"mobile": "+61468403453"
},
{
"contactId": "2",
"firstName": "Ben",
"lastName": "Jones",
"mobile": "+61411223451"
},
{
"contactId": "3",
"firstName": "Jenny",
"lastName": "Smith",
"mobile": "+61415303681"
},
...
]
}'
Response:
{
"warnings": [],
"started": 100
}
The reply indicates that all 100 contacts were started successfully. Now we sit back and let the Gopher handle the replies.
Conversation Outputs / Campaign Results
Let's assume you want to receive real time results. You start by contacting support@rungopher.com to register a webhook url.
When you've registered a webhook url, then once you start a campaign and customers reply, you will begin to receive results POSTed to your webhook url. Above we sent out an SMS campaign asking 100 users if they would like to convert to email. Let's work through the replies we receive and how they are sent to your webhook:
Accepted
Let's say Mark receives the SMS and replies "Yes please!". You will receive the following POST to your webhook, letting you know that he has agreed to convert to email:
{
"campaignId": 15,
"campaignToken": "0257a297-d0dd-4c90-a2d6-3c61b19360b9",
"contactId": "1",
"id": 100122,
"resultType": "boolean",
"resultName": "convertedToEmail",
"data": {
"answer": "yes"
},
"context": "Yes please!",
"timestamp": "2017-11-14T10:56:14Z"
}
Gopher will then say: "Great, could you please tell me your email?", and when he replies with his email, at that point, you will receive this POST:
{
"campaignId": 15,
"campaignToken": "0257a297-d0dd-4c90-a2d6-3c61b19360b9",
"contactId": "1",
"id": 100234,
"resultType": "email",
"resultName": "newEmail",
"data": {
"email": "mark.jones@gmail.com"
},
"context": "Sure, my email is: mark.jones@gmail.com",
"timestamp": "2017-11-14T11:00:14Z"
}
Declined
If Ben says something like "No way, I love getting snail mail", then when the Gopher receives that SMS, you will receive this POST:
{
"campaignId": 15,
"campaignToken": "0257a297-d0dd-4c90-a2d6-3c61b19360b9",
"contactId": "2",
"id": 100330,
"resultType": "boolean",
"resultName": "convertedToEmail",
"data": {
"answer": "no"
},
"context": "No way, I love getting snail mail",
"timestamp": "2017-11-14T11:23:14Z"
}
Transitions
If Jenny replied immeditately with a question (eg. how did you get my number?), or says something that the Gopher doesn't understand, then a transition email will be sent to your transition email address. You will not receive any POSTs when this happens.
Wrong number
If someone else that we sent to replied to say "Sorry but I think you have got the wrong number", you will get:
{
"campaignId": 15,
"campaignToken": "0257a297-d0dd-4c90-a2d6-3c61b19360b9",
"contactId": "8",
"id": 100657,
"resultType": "boolean",
"resultName": "wrongNumber",
"data": {
"answer": "yes"
},
"context": "Sorry but I think you have got the wrong number",
"timestamp": "2017-11-14T12:01:14Z"
}
The cancelled and optedOut results are delivered in a similar way, as appropriate.
Alternatively, if they said they would prefer to be contacted on another number:
{
"campaignId": 15,
"campaignToken": "0257a297-d0dd-4c90-a2d6-3c61b19360b9",
"contactId": "27",
"id": 100740,
"resultType": "phone",
"resultName": "newNumber",
"data": {
"phone": "+61400222111"
},
"context": "Actually could you please send to my work number, it's 0400 222 111",
"timestamp": "2017-11-14T01:23:14Z"
}
New address
Finally, a few of our solutions focus on confirming postal addresses. If a respondent replies with a new address, you'll receive:
{
"campaignId": 15,
"campaignToken": "0354ea2a-d0a5-01f0-2300-089d24936a04",
"contactId": "1",
"id": 100801,
"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-14T01:27:14Z"
}