MAPI Getting Started

MAPI Getting Started Guide


Audience

This document is intended for programmers who want to write applications that can interact with the Multi-dimensional Communication Platform (MCP) system. It provides a series of examples of basic API interactions. These examples come in the form of raw HTTP requests.

This document assumes that you understand the general ideas behind the MCP system. For general MCP information, see the Getting Started Guide.

Top

API Introduction

Overview

The APIs are grouped into the following sections:

  • System management: contains retrieving system related data, retrieving and updating organisation related information, retrieving and updating of the account bill rate for an organisation.
  • User management: contains user related functions such as sign-up and sign-in, user settings, retrieving and updating the users.
  • Broadcast management: contains broadcast related business transactions, create a broadcast, retrieving and updating of a broadcast, changing the status of a broadcast, and retrieving the replies of a broadcast.
  • Service management: contains service related business transactions, create a service, retrieving and updating of a service, and changing the status of a service.
  • Agile management: contains agile related business transactions, create an agile, retrieving and updating of an agile, changing the status of an agile, and retrieving the replies of an agile.
  • Dialog map management: contains creating a dialog map, retrieving and updating a dialog map, adding and removing a link/node from a dialog map.
  • Contact book management: contains creating a contact book, adding and removing a column from a contact book, retrieving and updating a contact book.
  • Contact group management: contains creating a contact group, retrieving and updating of a contact group, add a group and load contacts to it.
  • Contact management: contains adding a contact to a contact group, retrieving and updating a contact from a contact group, load contacts from a file to a contact group.
  • Organisation file management: contains searching through files, retrieving and updating of a file, adding and removing a file.
  • Router management: contains searching routers, retrieving and updating of a router, adding and removing a router.
  • Gateway management: contains searching gateways, retrieving and updating of a gateway, adding and removing a gateway.

Authentication

You authenticate to the MAPI by providing one of your login credentials in the request. All API requests can be made over HTTPS and plain HTTP. You must authenticate for all requests.

There are three ways of authenticating the user:

  • Providing the login_name and login_passwd.
  • Providing the login_name and session_id: the session_id can be obtained via LOGIN and CHECKIN.
  • Providing the device_id: a unique token provided by users when they sign in via LOGIN.

Requests and Responses

All API can be accessed over HTTP and HTTPS. The base address of the API is app02.yvntech.com. All data is received in XML format by default. JSON formatted responses are also supported by setting the "sys_response_data_format" value in the query parameters to "json" when making a request.

Parameters

Many API methods take optional parameters. These parameters are listed separately from the required ones. You should at least provide the parameters within the Required Parameters section to ensure the function works.

Permissions

MAPI leverages User Role to grant permissions to a user request. You need to have any of the roles listed within the Role Permitted section to make the request.

There are four different user roles:

  • Manager: the user who performs the core business transactions of MCP.
  • Admin: the administrator of an organisation. It has the rights to perform actions within the organisation.
  • Account manager: the account manager. It can manage the admin users and perform operations for all organisations.
  • Root: the super user of the system. It has all the rights to manage all users and across organisations.

HTTP Verbs

The following two types of HTTP verbs are supported to call each function:

  • GET: Used for retrieving resources.
  • POST: Used for creating resources, or performing custom actions.

Errors

MAPI uses data attributes of the response XML to indicate success or failure of an API request. If infotype equals 1, it means the request has failed or the request is invalid. An error message will also be included in the XML, letting you know what the problem is. If infotype is 0, it indicates success of the request.

Smart Content

You can include strings which have special meanings within the parameter values of certain API requests. Below is a table of those strings:

Note: The string patterns are all case sensitive.

Top

API Reference

For a detailed list of API, see the MAPI Manual.

Top

Tutorials

Sample Workflow

Top

Example

The following scenario is based on the SMS marketing campaign.

Step 1: Create a contact group

Create a contact group called “Customers”:

Given below are the descriptions of the parameters:

  • contactbook_id: 1. This is the default contact book. Its columns are name, mobile and email.
  • description: The recipients of our SMS marketing campaign. This value needs to be URL encoded and the result is “The%20recipients%20of%20our%20SMS%20marketing%20campaign”.

Step 2: Add a contact to the contact group

Add a contact to the “Customers” group:

Given below are the descriptions of the parameters:

  • contactgroup_id: 136. Enter the ID of the “Customers” contact group.
  • data_format: url_type. This value specifies how the contact data is represented within the request.
  • 1: Steven. The name of the contact.
  • 2: +61400000000. The contact’s mobile number. This value needs to be URL encoded and the result is “%2B61400000000”.
  • 3: steven@example.com. The contact’s email. After URL encoding, this value becomes “steven%40example.com”.

Step 3: Load contacts to the contact group

Load contacts from a file to the “Customers” group:

<html> <body> <form method="POST" enctype="multipart/form-data" action="http://app02.yvntech.com/MapIHttpS/MapIS?action=LOAD_CONTACT_TOCONTACTGROUP"> <p>Login name:<input type="text" name="login_name" value="" /></p> <p>Password:<input type="password" name="login_passwd" value="" /></p> <p>Contact group ID:<input type="text" name="contactgroup_id" value="136" /></p> <p>Field map:<input type="text" name="field_map" value="1_1,2_2,3_3" /></p> <p>Delimiter:<input type="text" name="delimiter" value="," /></p> <p>First line contains title?<input type="text" name="firstlineistitle" value="1" /><p> <p>Choose file:<input type="file" name="contact_file"/></p> <input type="submit" value="Submit" /> </form> </body> </html>

Complete the form, choose the contacts file and submit. The format of the contacts file is illustrated as follows:

Step 4: Add an agile by stencil and start it

Create an agile SMS with the title “Promotions Text for Weekend” and start sending it:

Given below are the descriptions of the parameters:

  • agile_title: Promotions Text for Weekend. After URL encoding, this value is “Promotions%20Text%20for%20Weekend”.
  • keep_draft: ON. The draft will be saved.
  • funtemplate_id: 100. This is the template ID for agile SMS.
  • funtemplate_stencil_id: 2. This stencil is used for sending agile SMS to a contact group.
  • xlabel11: 136. Enter the ID of the “Customers” contact group.
  • xlabel12: 2. This is the ID for the mobile column of the default contact book.
  • xlabel13: Visit our shop this weekend and get 50% off all our products. This is the SMS content. After URL encoding, this value becomes “Visit%20our%20shop%20this%20weekend%20and%20get%2050%25%20off%20all%20our%20products”.
  • xlabel_id_list: 10_1,11_25,12_22,13_10001. This ID list specifies the fields that are needed to create the agile SMS. After URL encoding, this value becomes “10_1%2C11_25%2C12_22%2C13_10001”.
Top

Getting Help

If you would like to get technical support or report errors, please send an email to support@yvntech.com.

Top