Messenger API / Web Service Details

The following page provides and overview of the API used to connect to synchronise data with and to send a message via Groupcall Messenger

Data Sync

This web-service is on the following address (http or https)

https://messengerOnline.groupcall.com/WebServices/Data.asmx

API_Data

dataChange

The dataChange method is for transmitting data changes to the Messenger Online database, a Messenger Online API key or username / password combination is required for authorising the call. Each call then has a type either Add, Update or Delete. Then arrays of contacts, addresses, attributes, groups and groupMemberships.

If the username & password combination is supplied then the user needs to be in the role ‘uploadData’. If the API key is specified then the username & password is not checked and should not be sent.

A string is returned, with the result of the call, each array row is processed separately, if there is an error on a row then you will get a line in the return indicating which row had the error. E.g. ‘Error :  ID is null at contact row 1’ If there are more than 20 errors in a single call then processing will be stopped.

 

Currently Add and Update both are identical; first the data is searched for then if present is updated, else is added.

Calls to the web-service for add & delete calls obviously need to be separated, also to aid scalability, system responsiveness etc. calls should be batched into arrays of no more than 100 at a time.

contacts

An array of contacts to add or delete. When deleting only the ID is required. When deleting a contact you do not need to delete the attributes, addresses or groupMemberships. Delete of a contact automatically deletes all the other links, if the contact has been sent messages in the past then the actual contact record will not be deleted.

contact

ID Unique ID for this contact in your account Varchar(20)
Forename Firstname for this contact, when sending a message $forename$ is replaced with this value. Varchar(50)
Surname Surname for this contact, when sending a message $surnaem$ is replaced with this value. Varchar(50)
Name If specified set the full name for this contact, if not specified then is a concatenation of forname and surname. When sending a message $name$ is replaced with this value. Varchar(100)

 

addresses

A list of addresses to add, update or delete. The ID is not currently used by Messenger Online  as it processes the array, the ContactID, type and location are used as the primary key in this table. Therefore to delete an address you will need to pass the contacted type and location.

address

ID Unique ID for this address
ContactId The ID of the contact for this address Varchar(20)
type Type for the address ‘telephone’ or ‘email’ are currently the only supported types. Varchar(20)
location Location description for this address. E.g. Mobile or Home or Work Varchar(20)
value The phone number or email address. If the phone number is not an international number (starts with + or 00) then the account country code will be prepended before a message is sent. Varchar(400)

groups

A list of groups to add, update or delete. The ID is used by Messenger Online for this group, so a delete only requires the ID. A delete of a group automatically deletes all memberships, so do not send deletes for all memberships when you delete a group.

group

ID Unique ID for this group Varchar(40)
type Type for this group, this is used as the top level of tree list of groups in the Messenger Online application. E.g. ‘Year Group’, or ‘Branch’. Varchar(20)
name Name of this group, displayed in the Messenger Online tree list with a check box, to select all the contacts. E.g. ‘Year 1’ or ‘Basingstoke’ Varchar(50)

 

groupMembership

A list of group memberships  to add, update or delete. The ID is not used by Messenger Online so a delete will require the contactId and the GroupId to be specified.

Membership

ID Unique ID for this group membership Varchar(40)
GroupId The ID for this group as already created in the groups section Varchar(40)
ContactID The ID for this contact as already created in the contacts section Varchar(20)

attributes

A list of contact attributes to add, update or delete. The ID is not used by Messenger Online so a delete will require the contactId and the attribute name to be specified. These attributes can then be used to replace a value in a message.

attribute

ID Unique ID for this contact attribute Varchar(40)
ContactID The ID for this contact as already created in the contacts section Varchar(20)
name Name of this attribute, this can then be used in messages as $name$e.g. ‘appointment’ or ‘EnglishGrade’ Varchar(20)
Value Value for this attribute, this value will be used when replacing the tokens in a message. E.g. ‘Tuesday 12:45’ or ‘A – very good’ Varchar(20)

SendMessage

This web-service is on the following address (http or https)

https://MessengerOnline.groupcall.com/WebServices/SendMessage.asmx

Send_Message

sendText

Send an SMS to one or more contacts. Username and password needs to be specified and the user needs to be in the ‘authoriseMessage’role.

Parameters:       Username, Password, message

Returns :              sendTextResult

Third party’s can send on behalf of a specific account by passing the accountcode followed by @ and the thirdparty name in the username and the thirdparty secret as the password. E.g. <username>3284321@partner</username><password>partnersecret</password>  then provided the account with code 3284321 has enabled the third party the message will be sent for that account.

message

 

savedMessageFolder If specified then the taxed in a presaved message will be used rather than the smsText being passed with the call. Varchar(40)
savedMessageName Varchar(40)
smsText The text to send, if no savedMessageFolder & Name not specified. Varchar(500)
contacts A contact array to send the message to.

contact

ID The contact ID of a contact uploaded with the data api or who has been sent a message previously. If not specified then the mobileNumber will be used. Varchar(40)
mobileNumber The number to be sent to, if not specified then the telephone number of the contact where location=‘Mobile’ will be used. Varchar(40)
forename The forename for the recipient used to replace the $forename$ token when sending the message. If not specified then the saved value for the contact will be used. Varchar(50)
surname The surname for the recipient used to replace the $surname$ token when sending the message. If not specified then the saved value for the contact will be used. Varchar(50)
name The name for the recipient used to replace the $name$ token when sending the message. If not specified then the saved value for the contact will be used. Varchar(100)
contactAttributes An array of name value pairs to be used as tokens when sending the message.


sendTextResult

errorMsg If set then there was an error Varchar(1000)
messageSentId If >0 then the id for this messageSent – use this ID when calling getTextStatus int
statusMsg String description of this message Varchar(1000)
transmitDateTime Date of transmission of this message (GMT)
Status An array of SMSMessageStatus elements detailing each mobile number and the status of the message


SMSMessageStatus

mobileNumber The number that the message was sent to Varchar(20)
Status Status string for this Text Varchar(1000)

 

getTextStatus

Get the SMS text status for a previously sent message .

Username and password needs to be specified and the user needs to be in the ‘authoriseMessage’ role.

Parameters:

Username

Password

messageSentId

Returns : getTextStatusResult

getTextStatusResult

errorMsg If set then there was an error Varchar(1000)
messageSentId If >0 then the id for this messageSent – use this ID when calling getTextStatus int
statusMsg String description of this message Varchar(1000)
transmitDateTime Date of transmission of this message (GMT)
Status An array of SMSMessageStatus elements detailing each mobile number and the status of the message

 

SMSMessageStatus

mobileNumber The number that the message was sent to Varchar(20)
Status Status string for this Text Varchar(1000)

 

 

 

sendTextWithCallback

Send an SMS to one or more contacts, with status changes to be called back. An extension of the sendText method, 2 additional parameters are added clientRef and callbackUrl.

 

Parameters:       Username, Password, message, clientRef, callbackUrl

Returns :              sendTextResult

clientRef A string reference that will be included in the callback Varchar(50)
callbackUrl The url of the callback server. HTTP GET will be used to push status changes to your server.Parameters passed as part of the get by default are:sentid Internal id for this sendcontactid=         Internal contactidexternalid         Your contact referenceclientref           clientRef from the call to sendTextWithCallback

recipient           Formatted mobile phone number used

status                  the status string

err                         error message if available

 

You can customise the url called by including a ? in the url and specifying your own parameters, placeholders can be put in your url using {}

e.g.

www.example.com?source=groupcall&ref={clientref}&studentid={externalid}&message={status}

 

If no ? is included in the url passed then the url will automatically be appended with

?sentid={sentid}&contactid={contactid}&externalid={externalid}&clientref={clientref}&recipient={recipient}&status={status}&err={err}

 

Varchar(400)

 

 

 

 

 

Single Sign On

This web-service is on the following address (http or https)

https://MessengerOnline.groupcall.com/WebServices/SSO.asmx

SSO

GetSingleUseToken

Send a username & password and get back a time limited single use token for passing to Messenger Online.groupcall.com (or messengeronline.groupcall.com)

Parameters:       thirdPartyName, thirdPartySecret, username, password

Returns :              token (guid string)

Thirdparty name and secret will be supplied on request to confirmed Groupcall partners, these should be kept secret and not distributed with your application. The username and password supplied are the alert / messengeronline credentials.

Token returned can then be used to forward the users browser onto https://alert.groupcall.com?Ssotoken={insert token here}

Or
https://messengeronline.groupcall.com?Ssotoken={insert token here}

 

Current timeout for the token is 5 minutes or first use.

 

GetSingleUseTokenUrl

Send a username & password and get back a time limited single use url for forwarding the user onto, same as the above GetSingleUseToken call except instead of returning the token returns the token appended to

Parameters:       thirdPartyName, thirdPartySecret, username, password

Returns :              url string

Thirdparty name and secret will be supplied on request to confirmed Groupcall partners, these should be kept secret and not distributed with your application. The username and password supplied are the alert / messengeronline credentials.

Url returned will then be something like https://MessengerOnline.groupcall.com?Ssotoken={guid}

 

 

 

 

 

Appendix A – dataChange soap

https://MessengerOnline.groupcall.com/WebServices/Data.asmx?op=dataChange

<soap:Body><dataChange xmlns="http://alert.groupcall.com/"><crud><username>string</username><password>string</password>

<APIKey>string</APIKey>

<type>Add or Update or Delete</type>

<contacts>

<Contact>

<ID>string</ID>

<forename>string</forename>

<surname>string</surname>

<name>string</name>

</Contact>

<Contact>

<ID>string</ID>

<forename>string</forename>

<surname>string</surname>

<name>string</name>

</Contact>

</contacts>

<addresses>

<Address>

<ID>string</ID>

<ContactId>string</ContactId>

<type>string</type>

<location>string</location>

<value>string</value>

</Address>

<Address>

<ID>string</ID>

<ContactId>string</ContactId>

<type>string</type>

<location>string</location>

<value>string</value>

</Address>

</addresses>

<attributes>

<Attribute>

<ID>string</ID>

<ContactId>string</ContactId>

<name>string</name>

<value>string</value>

</Attribute>

<Attribute>

<ID>string</ID>

<ContactId>string</ContactId>

<name>string</name>

<value>string</value>

</Attribute>

</attributes>

<groups>

<Group>

<ID>string</ID>

<type>string</type>

<name>string</name>

</Group>

<Group>

<ID>string</ID>

<type>string</type>

<name>string</name>

</Group>

</groups>

<groupMembership>

<Membership>

<ID>string</ID>

<ContactId>string</ContactId>

<GroupId>string</GroupId>

</Membership>

<Membership>

<ID>string</ID>

<ContactId>string</ContactId>

<GroupId>string</GroupId>

</Membership>

</groupMembership>

</crud>

</dataChange>

</soap:Body>

 

Appendix B – sendText

https://MessengerOnline.groupcall.com/WebServices/SendMessage.asmx?op=sendText

<soap:Body>

<sendText xmlns="http://groupcallalert.com/">

<userName>string</userName>

<password>string</password>

<message>

<savedMessageFolder>string</savedMessageFolder>

<savedMessageName>string</savedMessageName>

<smsText>string</smsText>

<sendDateTime>dateTime</sendDateTime>

<contacts>

<Contact>

<ID>string</ID>

<mobileNumber>string</mobileNumber>

<forename>string</forename>

<surname>string</surname>

<name>string</name>

<contactAttributes xsi:nil="true" />

</Contact>

<Contact>

<ID>string</ID>

<mobileNumber>string</mobileNumber>

<forename>string</forename>

<surname>string</surname>

<name>string</name>

<contactAttributes xsi:nil="true" />

</Contact>

</contacts>

</message>

</sendText>

</soap:Body>

Appendix C – sendTextResponse

https://MessengerOnline.groupcall.com/WebServices/SendMessage.asmx?op=sendtextResponse

<soap:Body>

<sendTextResponse xmlns="http://groupcallalert.com/">

<sendTextResult>

<errorMsg>string</errorMsg>

<MessageSentId>int</MessageSentId>

<statusMsg>string</statusMsg>

<transmitDateTime>dateTime</transmitDateTime>

<status>

<SMSMessageStatus>

<mobileNumber>string</mobileNumber>

<status>string</status>

</SMSMessageStatus>

<SMSMessageStatus>

<mobileNumber>string</mobileNumber>

<status>string</status>

</SMSMessageStatus>

</status>

</sendTextResult>

</sendTextResponse>

</soap:Body>

Appendix D – sendTextWithCallback

https://MessengerOnline.groupcall.com/WebServices/Data.asmx?op=sendTextWithCallback

<soap:Body>

<sendTextWithCallback xmlns="http://groupcallalert.com/">

<userName>string</userName>

<password>string</password>

<message>

<savedMessageFolder>string</savedMessageFolder>

<savedMessageName>string</savedMessageName>

<smsText>string</smsText>

<sendDateTime>dateTime</sendDateTime>

<contacts>

<Contact>

<ID>string</ID>

<mobileNumber>string</mobileNumber>

<forename>string</forename>

<surname>string</surname>

<name>string</name>

<contactAttributes xsi:nil="true" />

</Contact>

<Contact>

<ID>string</ID>

<mobileNumber>string</mobileNumber>

<forename>string</forename>

<surname>string</surname>

<name>string</name>

<contactAttributes xsi:nil="true" />

</Contact>

</contacts>

</message>

<clientRef>string</clientRef>

<callbackUrl>string</callbackUrl>

</sendTextWithCallback>

</soap:Body>