Two Way Messaging API Page
Back to API Home

  1. API Specification
  2. Sample Code
  3. Sample XML Responses
  4. Response Codes
API Specification

Two Way Messaging


When a user texts a message to a developer's keyword, we will post the text, tagg, and transaction ID to that developer's callback URL (set here). The developer will be able to make a decision based on the text and send a response to the user using the same transaction ID.

Order of Events:

  1. User texts a message to one of the developer's custom API variables
  2. We post the following values to the callback URL the developer has specified on the Account Page:
       transaction_id - ID assigned by tagga, developer needs this to respond to the specific message
       tagg - Developer API keyword, used to differentiate between applications
       message - The message text the user sent via SMS to the developer
  3. The developer has 30 minutes to respond, see the following for more details.

Callback URL (tagga posts to this URL):
This is developer specified on the API Account Page.

Callback Parameters:
  1. transaction_id - Transaction ID of the incoming message.
  2. tagg - Custom API keyword
  3. message - Message content sent to developer

POST URL (developer posts to this URL):
http://tagga.com/api/response/

POST Parameters:
  1. apikey - Developer API key, retrieve from API account at tagga.com
  2. passkey - Developer Password key, emailed to developer when API account approved
  3. tagg - Custom API keyword, developer specified at tagga.com
  4. transaction_id - Transaction ID of inbound message that this API call is a response to
  5. message - Message content sent to user, must be between 0 and 100 characters for the latin character set, and 0 and 50 for all others. If message is paid, message content can be between 0 and 140 characters for the latin character set, and 0 and 70 for all others.
  6. paid - Set to TRUE to send a sponsor-free text message, FALSE otherwise. Enables developer to send message containing up to 140 characters. Setting to TRUE requires that developer have valid payment (Optional). The price is $0.10 USD per message.

Restrictions:

  1. Developer can only respond to an incoming message once
  2. Two way transaction times out in half an hour, meaning developer can not reply after 30 minutes have passed
  3. If a developer sends a message set as paid and does not have payment registered at tagga.com, developer will receive error code 18.

Response:
An XML response is returned and details a unique transaction ID, response code, and response message. You are responsible for checking the response message and acting appropriately.

Back to top
Sample Code

PHP


// get the parameters that tagga has posted
$transactionId = $_POST['transaction_id'];
$tagg = $_POST['tagg'];
$message = $_POST['message'];

// this is where you would handle the incoming message
// and determine how to respond

$postdata = http_build_query(
  array(
    'apikey' => 'abc123', // put your API key here
    'passkey' => '321cba', // put your API password key here
    'tagg' => $tagg, // the tagg you have reserved for this application
    'transaction_id' => $transactionId, // Transaction ID, to link response to original request.
    'message' => 'This is your response to the user based on what they sent to you.'
  )
);

$opts = array(
  'http' => array(
    'method' => 'POST',
    'header' => 'Content-type: application/x-www-form-urlencoded',
    'content' => $postdata
  )
);

$context = stream_context_create($opts);
$response = file_get_contents(
  'http://tagga.com/api/response/',
  false,
  $context
);

// handle the response message


Python


import urllib
import cgi

# get the parameters that tagga has posted
form = cgi.FieldStorage()
transaction_id = form['transaction_id'].value
tagg = form['tagg'].value
message = form['message'].value

# this is where you would handle the incoming message
# and determine how to respond

apikey = u'abc123' # put your API key here
passkey = u'321cba' # put your API password key here
message = u'This is your response to the user based on what they sent to you.'

postdata = urllib.urlencode({'apikey': apikey, 'passkey': passkey, 'tagg': tagg, 'transaction_id': transaction_id, 'message': message})

response = urllib.urlopen('http://tagga.com/api/response/', postdata)

# handle the response message


Java


// this example assumes that this code is within the doGet()
// function of a class that extends HttpServlet
try {

  String transactionId = req.getParameter("transaction_id");
  String tagg = req.getParameter("tagg");
  String message = req.getParameter("message");

  // this is where you would handle the incoming message
  // and determine how to respond

  String postdata = URLEncoder.encode("apikey", "UTF-8") + "=" + URLEncoder.encode("abc123", "UTF-8");
  postdata += "&" + URLEncoder.encode("passkey", "UTF-8") + "=" + URLEncoder.encode("321cba", "UTF-8");
  postdata += "&" + URLEncoder.encode("tagg", "UTF-8") + "=" + URLEncoder.encode(tagg, "UTF-8");
  postdata += "&" + URLEncoder.encode("transaction_id", "UTF-8") + "=" + URLEncoder.encode(transactionId, "UTF-8");
  postdata += "&" + URLEncoder.encode("message", "UTF-8") + "=" + URLEncoder.encode("This is your response to the user based on what they sent to you.", "UTF-8");

  // Send data
  URL url = new URL("http://tagga.com/api/response/");
  URLConnection conn = url.openConnection();
  conn.setDoOutput(true);
  OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
  wr.write(postdata);
  wr.flush();

  // Get the response
  BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));

  // handle the response here
  wr.close();
  rd.close();
} catch(Exception exc) {

  // handle any exceptions
}


Back to top
Sample XML Responses

Sample Success Response


<?xml version="1.0" encoding="UTF-8"?>
<TaggaResponse version="1.0">
  <TransactionID>100</TransactionID>
  <ReturnCode>0</ReturnCode>
  <Message>Success - API function call successful</Message>
</TaggaResponse>

Sample Error Response


<?xml version="1.0" encoding="UTF-8"?>
<TaggaResponse version="1.0">
  <TransactionID>101</TransactionID>
  <ReturnCode>20</ReturnCode>
  <Message>Transaction Timeout - Developer did not respond to initial request soon enough</Message>
</TaggaResponse>

Back to top
Response Codes
0: Success - API function call successful
1: Invalid Recipient - Not on allowed recipient list
2: Authentication Failed - apikey and passkey not valid
3: Incomplete API Call - Not all required parameters passed in
5: Message Length Invalid - Message text must be between 0 and 100 characters (140 if paid) for the latin character set, and 0 and 50 (70 if paid) for all others
6: Invalid Input - Some or all of the required parameters are invalid
7: Unknown Remote Address - This IP address is not allowed
8: Unknown tagg - Input tagg cannot be found
18: No Valid Payment Found - Campaign not created or message not sent, no valid payment found
19: Invalid Transaction - Transaction does not exist or was already responded to
20: Transaction Timeout - Developer did not respond to initial request soon enough

Back to top

  • Mobile Carrier Approved
    No Spam 100% Opt-In

  • Create SMS &
    Mobile Site Campaigns

  • Watch our video!

    Watch our short claytorial to learn more about tagga…

  • Tagga API

    Join our developer program and use the tagga API to create SMS applications.

  • The eye of the tagga blog

    Tagga CEO, Amielle Lake, Featured in DMNEWS Text messages more effective than mobile...