Gumiyo – Developer API
Integrating with the Mobile Ready Platform
Overview
The Gumiyo developer API allows partners to integrate external systems with the
Gumiyo platform, and integrates mobile content and messaging to existing applications.
The API provides methods to send and receive text messages, to format text messages
and to allow developers to review the status of submitted requests.
Prerequisites
To integrate your application with the Gumiyo APIs, please make sure you have
completed the following steps:
1. You are a Gumiyo reseller, affiliate or value-added reseller and your current
affiliate agreement includes access to the Gumiyo platform through our APIs
2. You have received an API username and password. If you have not received your
API username and password, please contact support@gumiyo.com
3. You understand the current rate limits set forth in your affiliate agreement, and
your expected message volume does not exceed your rate limits.
4. You have an active short code that was provided to you by your Gumiyo account
manager or you are using the default short code for Gumiyo partners.
5. You have sufficient knowledge of using Web Services and have integrated other
web services into your existing platform.
Getting started
Your Gumiyo account administrator will configure your usage quota via the Partner
Accounts section of the administration screen
When setting up your account, you may provide your administrator with a Notification
URL. This URL will direct to a servlet or a CGI to which Gumiyo will provide the
following information per as the API calls are being perform asynchronously:
Notification URL, sent transactions:






gumiyoTransactionId – assign by Gumiyo on submit
transactionId – client transaction id
recipientId – client recipient id
messageId – client message id
processed (time as long) – time when the call was processed
status – the status code
Status codes: requested  ACK, scheduled  ACK, scheduled_retry  Schedule
by the system for a retry, sent  submitted to MSG gateway, delivered  delivered
to consumer (mBlox only), error Gateway error (we will not retry anymore),
cancelled  User actively canceled, denied  Basic validation did not pass (account
not configured for this short code, phone invalid, msg length), or quota maxed
Accessing the API:
The Gumiyo developer API is accessed through a Web Service call from your client. The
requests should be made from your server(s) over HTTP. In this document, the examples
are provided using the SOAP interface to access the web services. The complete
description of the Gumiyo Web Service API can be retrieved using the Web Service
descriptor at http://www.gumiyo.com/webservices/MsgWebServices?wsdl
There are several interfaces to the Gumiyo API

Messaging V2 [current version]
http://www.gumiyo.com/webservices/MsgWebServices?wsdl
o Send/ schedule messages to users, supports nested transactions
o Check status of scheduled messages/ cancel unsent messages
o Opt out subscribers

Messaging V1 [Older version]:
http://www.gumiyo.com/webservices/SMSWebServices?wsdl
o Send SMS messages, receive SMS messages, get the activity log for a
given user/ transaction ID

User Management:
http://www.gumiyo.com/webservices/UserWebService?wsdl
Create/ update User accounts, reserve Go Codes, check inventory import status
Authentication:
Each submitted API call requires the partner to include a <partner> section, in which the
partner will provide a partner name and password. The partnerName and partnerPassword
fields of the partner section are used by the Gumiyo platform to identify each submitted
call and associate it with an account.
Example:
<partner>
<partnerName>test</partnerName>
<partnerPassword>gumiyo</partnerPassword>
</partner>
Sending a message:
The “send” method allows a partner to send one or more messages.
<soapenv:Header/>
<soapenv:Body>
<msg:send>
<partner>
<partnerName>test</partnerName>
<partnerPassword>gumiyo</partnerPassword>
<partnerTransactionId>pt1</partnerTransactionId>
</partner>
<sendService>
<message>
<content>Dear {data:firstName,default:NoName} {data:lastName}, the price is
{data:price,format:"%d", default:-1} see {page:"My Specials"} or
{link:http://www.yourserver.com}</content>
<partnerMessageId>m1</partnerMessageId>
</message>
<recipient>
<partnerRecipientId>p1</partnerRecipientId>
<subscriberNumber>8182793315</subscriberNumber>
<data>{firstName:Shuki, lastName:‘Lehavi'}</data>
</recipient>
<schedule>
<!-- send in 5 minutes -->
<at>+5</at>
</schedule>
<shortCode>48696</shortCode>
</sendService>
</msg:send>
</soapenv:Body>
Status method, using selectors
Cancel, using selectors
Optout
Report
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:msg="http://www.gumiyo.com/webservices/MsgWebService">
<soapenv:Header/>
<soapenv:Body>
<msg:report>
<!--Optional:-->
<partner>
<!--Optional:-->
<partnerName>?</partnerName>
<!--Optional:-->
<partnerPassword>?</partnerPassword>
<!--Optional:-->
<partnerTransactionId>?</partnerTransactionId>
</partner>
<!--Optional:-->
<reportService>
<!--Optional:-->
<reportName>?</reportName>
</reportService>
</msg:report>
</soapenv:Body>
</soapenv:Envelope>
Web to Mobile Interceptors
Before you start
Make sure you know have created a Gumiyo site, and were assigned a Go Code. The
examples throughout this document are noted with GOCODE where you need to insert
your assigned Go Code.
Overview
Web-to-Mobile interceptors provide partners with a set of solutions designed to redirect
traffic from traditional web sites to mobile sites. The purpose of the redirect products is
to:

Route visitors using a mobile device to a mobile-friendly version of your main
website, thus creating a better user experience for on-the-go users.

Allow users to send content to their mobile phone or forward content to other
users
JavaScript Redirect
If you are hosting your own site, mobile phones that support JavaScript (e.g. iPhone,
Google Android based phones) can be redirected to a mobile version of your site that is
hosted on the Gumiyo platform. To do so, the following code needs to be incorporated
into the top section of your HTML pages:
<script language="javascript1.2">
<!-if (screen.width >= 639) {
}
else {
window.location.replace('http://GOCODE.gumiyo.com/?m=b')
};
//-->
</script>
How it works:



The code inspects the screen size and redirects incoming requests where the
screen width is lower than 639 pixels to the mobile site.
The mobile site is accessed via 'http://GOCODE.gumiyo.com/?m=b’. Example, if
your Go Code is ABC then the URL will be http://ABC.gumiyo.com/?m=b. Note
that Go Codes are case insensitive (ABC is the same as abc).
The m=b parameter at the end of the URL forces the Gumiyo platform to redirect
the user to a mobile site
Redirecting a sub-domain (CNAME)
Some websites use a sub domain (m.yourcompany.com) or a separate domain name
(yourcompany.mobi) to house their mobile site. To redirect your sub domain, create a
CNAME record with your DNS or your website hosting service and map the CNAME to
http://www.gumiyo.com. Once the CNAME is in place, inform your Gumiyo
administrator who will then enable the domain forwarding on the Gumiyo platform
Web-to-mobile widgets
Web-to-mobile widgets allow consumers to forward existing web content to mobile
phones. Using the widget, consumers can enter a phone number and the Gumiyo platform
will send a link to a mobile page to that number. The mobile page can be the main page
of the mobile site, a specific page on the mobile site, or even a result of a search through
the inventory presented on the mobile site.
The most basic form of a widget can be automatically generated by calling a URL and
passing your Go Code. The URL is http://www.gumiyo.com/mq.p?a=sp&vin=GOCODE,
e.g. http://www.gumiyo.com/mq.p?a=sp&vin=ABC
The result of this call will display as a “Send To Phone” widget with the default graphic
of a vehicle:
If you inspect the generated code (click on View  Source on the generated HTML
frame), you will notice the following code:
<html>
<head>
<script type="text/javascript">
function stripAlphaChars(field) {
var m_strOut = new String(field.value);
m_strOut = m_strOut.replace(/[^0-9\.]/g, '');
field.value = m_strOut;
return true;
}
</script>
</head>
<body>
<input type="hidden" name="color" value=""/>
<div id="sendToPhoneContainer">
<img src="/web/common/images_v3/icons/hd_web2phone_car.png" alt="Send to Phone" width="148"
height="30"
border="0">
<div class="clear"></div>
<div id="formContainer">
<form action="mq.p" method="post">
<input type="hidden" name="a" value="sp"/>
<input type="hidden" name="dialog.message" value="GOCODE"/>
<input type="hidden" name="dialog.service_code" value=""/>
<label for="sendToPhone">Your mobile number:</label><input type="text"
id="sendToPhone"
name="dialog.umda"
size="10" maxlength="10"
onKeyUp="stripAlphaChars(this);"
class="floatleft" style="margin-right:5px;"/>
<input name="Send" type="image"
src="/web/common/image/buttons/btn_send_red.png" alt="Send"
border="0">
<br/>
<span class="smalltext">*Std text msg rates may apply.</span>
</form>
</div>
</div>
</body>
</html>
The generated code includes the following:
1. stripAlphaChars JavaScript function intended to strip non alphanumeric
characters from the phone number field, as such “(818)456-1234” will be turned
into 8184561234
2. An HTML FORM element with the following fields:
a. Hidden field with name “a” and value “sp” – required.
b. Hidden field with name “dialog.message” and value is your Go Code. The
value in this field can be the Go Code (e.g. ABC) or the Go Code + space
+ keyword (e.g. ABC SPECIALS). The keyword can be a search term, or
used point to specific pages. For example, the value may be “ad123” to
search for an ad with coupon code “ad123”. The value may be “specials”
to redirect the user to the mobile page that is associated with the “specials”
keyword through the Gumiyo administration console.
c. Hidden field with name “dialog.service_code”, value should be blank. A
text field with the name “dialog.umda” which is used to contain the value
of the consumer’s phone number
d. A default submit button.
Note:


You are free to create your own widgets as long as they form an HTTP request
that contains the fields mentioned above.
Try calling http://www.gumiyo.com/mq.p?a=sp&vin=GOCODE+AD123 and you
will notice that the value in the generated HTML for the “dialog.message” field is
"GOCODE AD123"