Mobilize Us API Guide

An application programming interface (API) is an interface that a software program implements in order to allow other software to interact with it, much in the same way that software might implement a user interface in order to allow humans to use it. Another words, an API in the context of web development allows remote website such as: http://www.yourwebsite.com the ability to access the orginating websites resources.

How can the Mobilize Us API work for me?

The Mobilize Us API can allow your website to host texting services without your users having to come to Mobilize Us.

Our API will allow you to send group text messages from your own website and via cell phone.
Allows you to create a text messaging group.
Grants your website the ability to securely administrator your group members.
Allows you to directly submit SMS text messages to our gateway, thus bypassing our website.

I'm not a programmer... How can I get started using the Mobilize Us API?

The first thing that needs to be done is to conceptually figure out exactly how you would like to enable Mobilize Us group texting services on your website. The next step would be to ask / find a web programmer that is familiar with WSDL/SOAP API. You can then point she or he to this URL where they will be able to find all of the information they need to get started. At anytime, for more information you can contact support@mobilizeus.com

API reference & commands

Where do I begin the implementation of the Mobilize Us API?

In order to get started...

First you must obtain an API ID from support@mobilizeus.com which will grant you secure access to our texting services. Once you obtain your API ID, you will be able to begin writing the appropriate commands to remotely access our services.

AN EXAMPLE

Let's say your API ID is "D4T2IOJ876" and you wish to allow a user on your website to create a texting group on our system.
In order to do this you would issue the follow command to our system from a PHP script:

FUNCTION: CreateGroup($vars);

CODE:

ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
$client = new SoapClient("http://www.mobilizeus.com/api/SOAP/GROUP_create_group/GROUP_create_group.wsdl");
//Getting IP
$ip = $_SERVER['REMOTE_ADDR'];
//Format ( api_ID|ip|grouptitle|smstitle|summary|status|group password|subscriptionmsgcntmax )
$vars = "suutuwch54|$ip|api test group|apigroup|this is the summary of the group|2||";
$return = $client->CreateGroup($vars);
print_r($return);

VARIABLES/PARAMETERS EXPLAINED:

$ip = Your server's IP addresss (this is used as a part of authenication. This address must be a static IP)
$vars = These variables are parameters that are passed to our system in order to perform the function successfully.

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
grouptitle = The name you wish to call your group.
smstitle = The texting name of your group. i.e EXAMPLEGRP: This is a group test text messages to everyone in my group.
status = This parameter can be set to either 1 or 2.
group password = This parameter is for setting a group password to your group.
subscriptionmsgcntmax = The maximum amount of text messages this group is allowed. This value is also the amount of messages your group will start with.

1 = Only admins of your group can send messages.
2 = All group members can send messages to they texting group

OUTPUT:

Group created (groupid=$groupid). The next step is to use the add_group_member function to add an Admin and or other group members.

If for some reason when you execute the script above, you don't receive the OUTPUT above, our system will generate an error which should indicate where the problem lies.

Once your group has been successfully created, you can create some sub-groups (rolename) which is optional. If you choose not to create sub-groups (rolenames) then you must use the "member" or "admin" as sub-groups (rolenames) This done by issuing a seperate command to our API

FUNCTION: CreateRolename($vars);

CODE:

ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
$client = new SoapClient("http://www.mobilizeus.com/api/SOAP/GROUP_create_rolename/GROUP_create_rolename.wsdl");
//Getting IP $ip = $_SERVER['REMOTE_ADDR'];
//Format ( api_ID|ip|groupid|rolename )
$vars = "D4T2IOJ876|$ip|663|curve";
$return = $client->CreateRolename($vars);
print_r($return);

VARIABLES/PARAMETERS EXPLAINED:

OUTPUT:

Your new rolename (curve)(sub-group) has been created.

FUNCTION: AddGroupMembers($vars);

CODE:

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group rolename = The name you wish to call your sub-group. Unless you have created sub-groups in the above function, you must use either "admin" or "member" as a rolename. If you set the rolename="admin" this will make the user an admin of the group.
tel = The mobile phone number of the group member you are adding. This MUST be a 10-digit phone number without dashes periods, etc. i.e. 5556569001 fullname = The first and last name of the person you are adding to the group.
smsact = This parameter is determines whether or not the user you are adding mobile phone is activated with your system.

0 = Not activated (this person in your group will NOT receive group text messages).
1 = Activated (this person in your group WILL receive group text messages).

email_to_sms = This field specifies the cell phone carrier for delivering text messages via Email to SMS. This field is required if you are using Mobilize Us unlimited Email to SMS service. However it's not required if you are using our paid service. The parameters for this field are numerical (i.e. 12 or 13) and are as follows:

22 = Metro PCS
10 = At&t
11 = T-mobile
12 = Verizon
13 = Sprint
14 = Cricket
15 = US Cellular
16 = Boost Mobile
17 = Nextel
18 = Cingular
20 = ACS Wireless
21 = Alltel
23 = Virgin Mobile
24 = Cincinnati Bell Wireless

OUTPUT:

The user ($userid) has been added to the group ($groupid) with the rolename ($rolename) (roleid = $roleid).

How to delete members my group?

Once you have created and added people to your texting group, the next thing to do is send them a message! Below you will find the SOAP function designed to do just that.

FUNCTION: DelGroupMembers($vars);

CODE:

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group.
rolename = The name of the sub-group you wish to remove the member from.
tel = The mobile phone number of the group member you are removing. This MUST be a 10-digit phone number without dashes periods, etc. i.e. 5556569001

OUTPUT:

The user ($userid) has been removed from the group ($groupid) with the rolename ($rolename) (roleid = $roleid).

How to send text messages to my group?

Once you have created and added people to your texting group, the next thing to do is send them a message! Below you will find the SOAP function designed to do just that.

FUNCTION: MsgGroupMembers($vars);

CODE:

ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
$client = new SoapClient("http://www.mobilizeus.com/api/SOAP/GROUP_msg_group_members/GROUP_msg_group_members.wsdl");
//Getting IP
$ip = $_SERVER['REMOTE_ADDR'];
//Format ( api_ID|ip|groupid|tel|rolename|msg )
$vars = "D4T2IOJ876|$ip|663|5552566432|admin|This is a test messages from SOAP";
$return = $client->MsgGroupMembers($vars);
print_r($return);

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group.
rolename = The name of the sub-group you wish to send your message to. Substituting "Everyone" for the rolename will send you message out to everyone in your group.
tel = The mobile phone number of the group member you are adding. This MUST be a 10-digit phone number without dashes periods, etc. i.e. 5556569001 msg = This is the text message you want to send to your group.

OUTPUT:

Your messages will be delivered shortly.

Now that you have sent messages to your group what is next?

How do I know which users are admins of our group?

Say you want to check to see if a group member is an admin. Below you will find the SOAP function designed to do just that.

FUNCTION: ListAdmins($vars);

CODE:

ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
$client = new SoapClient("http://www.mobilizeus.com/api/SOAP/GROUP_list_admins/GROUP_list_admins.wsdl");
//Getting IP
$ip = $_SERVER['REMOTE_ADDR'];
//Format ( api_ID|$ip|groupid )
$vars = "D4T2IOJ876|$ip|676";
$return = $client->ListAdmins($vars);
print_r($return);

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group.

OUTPUT:

OUTPUT FOR ADMINISTRATORS FOR GROUPID = 663
FULLNAME: Jack Johnson|Debra Brown
TEL: 5553578124|5559699561
EMAIL to SMS: 10|10
PHONE ACTIVATED: 1|1

In the above example, we can see there are two admins. for the group with groupid = 663

Let's say you have created several groups using the CreateGroup($vars); function. How can you output all of the groups you have created?

Well, if you ever need to see all of the groups you have created via $groupid you can use the following function below:

FUNCTION: RefListGroups($vars);

CODE:

ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
$client = new SoapClient("http://www.mobilizeus.com/api/SOAP/GROUP_ref_list_groups/GROUP_ref_list_groups.wsdl");
//Getting IP
$ip = $_SERVER['REMOTE_ADDR'];
//Format ( api_ID|$ip|groupid|userid|rolename )
$vars = "D4T2IOJ876|$ip|663";
$return = $client->RefListGroups($vars);
print_r($return);

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group.

OUTPUT:

OUTPUT OF GROUPS (API_ID=D4T2IOJ876)

GROUPID: 5|663

Now that we can list the groups we have created, it's time to get a group member count, your sub-group/rolename's and roleid's.

You can use the following function below to view the details of a particular group ($groupid):

FUNCTION: RefListGroupsDetails($vars);

CODE:

ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
$client = new SoapClient("http://www.mobilizeus.com/api/SOAP/GROUP_ref_list_groups_details/GROUP_ref_list_groups_details.wsdl");
//Getting IP
$ip = $_SERVER['REMOTE_ADDR'];
//Format ( api_ID|ip|groupid|userid|rolename )
$vars = "D4T2IOJ876|$ip|663";
$return = $client->RefListGroupsDetails($vars);
print_r($return);

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group.

OUTPUT:

Want to see information regarding the users of a particular group?

You can use the following function below to view the details of a particular group members within a group:

FUNCTION: ListUsers($vars);

CODE:

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group.

OUTPUT:

OUTPUT OF USERS FOR GROUPID = 663
FULLNAME: Jack Johnson|Debra Brown
TEL: 5553578124|5559699561
EMAIL to SMS: 10|10
PHONE ACTIVATED: 1|1

If you should ever need to delete a group as well as all rolenames / sub-groups and users....

You can use the following function below to do so:

FUNCTION: DeleteGroup($vars);

CODE:

ini_set("soap.wsdl_cache_enabled", "0"); // disabling WSDL cache
$client = new SoapClient("http://www.mobilizeus.com/api/SOAP/GROUP_delete_group/GROUP_delete_group.wsdl");
//Getting IP
$ip = $_SERVER['REMOTE_ADDR'];
//Format ( api_ID|ip|groupid )
$vars = "D4T2IOJ876|$ip|663";
$return = $client->DeleteGroup($vars);
print_r($return);

VARIABLES/PARAMETERS EXPLAINED:

Format of parameters: Each parameter must be seperated by | as presented in the example above CODE:

api_ID = D4T2IOJ876
ip = Your static IP address.
groupid = The unique numeric ID of your group.

OUTPUT:

The group has been deleted (GROUPID = 663).