API Docs

Microapp APIs

Ayoba MicroApp API

Here you will discover how to use Ayoba MicroApp API, how to communicate with Ayoba API and obtain extra info to create better MicroApps.

Compose message

Ayoba.composeMessage(message); 

Puts a text on the compose bar of the chat screen without sending the message

ParametersType
messageString: message to put on the compose bar
Returns
No return value
Permissions
No permissions required

Example

Ayoba.composeMessage(message);

Get MSISDN

Ayoba.getMsisdn()

Gets the user MSISDN

Parameters
No parameters
Returns
String: the user’s MSISDN. Example: +93777777778
Permissions
MSISDN

Example

function getMsisdn() {
    var msisdn = Ayoba.getMsisdn();
    return msisdn
 }

Retrieve user location

onLocationChanged(lat, lon)

Gets the user location.

The MicroApp must implement this method to retrieve the location live data. When data is updated from Ayoba, then Ayoba calls this javascript method on MicroApp to pass the new data

Parameters
latLatitude coordinate. Example: 41.4203
lonLongitude coordinate. Example: 2.1828
Returns
No return value
Permissions
Location

Example

  function onLocationChanged(lat, lon) {
    currentLatitude = lat
    currentLongitude = lon
  }

Retrieve user presence

onPresenceChanged(presence)

Gets the user presence.

The MicroApp must implement this method to retrieve the user presence live data. When data is updated from Ayoba, then Ayoba calls this javascript method on MicroApp to pass the new data

Parameters
presenceuser presence
0: Offline
1: Online
Returns
No return value
Permissions
UserPresence

Example

function onPresenceChanged(presence) {
    currentPresence = presence
  }

Send message

Ayoba.sendMessage(message)

Sends a chat message directly without putting the text on the compose bar of the chat screen

Parameters
messageString: message to send directly
Returns
No return value
Permissions
SendMessage

Example

Ayoba.sendMessage(message);

Take and retrieve picture

Ayoba.takePicture();

Takes a picture with the phone’s camera.

Parameters
No parameters
Returns
responseCoderesponse code of the opening of the phone’s camera (1: success, -1: failure)
picturePathpicture’s path
Permissions
TAKEPHOTO

Example

function takePicture() {
    Ayoba.takePicture();
}

onPictureRetrievedResponse(responseCode, picturePath)

Gets the response code and path of the picture taken.

The MicroApp must implement this method to retrieve the picture taken's path. When data is updated from Ayoba, then Ayoba calls this javascript method on MicroApp to pass the new data

Parameters
responseCoderesponse code of the picture being saved on the external storage (1: success, -1: failure)
picturePathpicture’s path
Returns
No return value
Permissions
TAKEPHOTO

Example

function onPictureRetrievedResponse(responseCode, picturePath) {
    var responseCode = responseCode
    var picturePath = picturePath
}

Get Send Message

Ayoba.getCanSendMessage()

Gets if the user has accepted the permission to send a message

Parameters
No parameters
Returns
Boolean: The function returns true if user has accepted the permission to send a message; if not, returns false
Permissions
No permissions required

Example

Ayoba.getCanSendMessage()

Start Conversation

ayoba.startConversation(jid);

Sends an event to Ayoba application to start conversation on the MicroApp

Parameters
jid
Returns
No return value
Permissions
No permissions required

Example


string jid = "62c3bdfffc5c7c3bb30bc7beda52531d2d2df@dev.ayoba.me";
function startConversation() {
   ayoba.startConversation(jid);
  }

Send media

Ayoba.sendMedia(url, mimeType)

Sends a media chat message (image, video, audio, file or contact)

Parameters
urlString: the media file url
mimeTypeString: the mime type of the media file

The following table shows the allowed mime types

| Media type | Allowed mime types | | ---------------- | :----------------------- : | | Image | image/jpg image/jpeg image/png image/gif | |Video | video/mp4 | | Audio | audio/3gpp audio/ogg audio/mpeg audio/mp4 audio/wav audio/aac audio/flac| | File | application/pdf application/msword | | Contact | text/x-vcard text/vcard |

Returns
No return value

The following method must be implemented to retrieve the call response:

function onMediaSentResponse(responseCode, encodedUrl)

Parameters
responseCode
1: the media file has been sent successfully
-1 the media file could not be sent because exceeds the maximum file size (35 MB)
-2: the media file could not be sent because the mime type is invalid
-3: the media file could not be sent because the file extension is invalid
-4: the media file could not be sent because the user has not accepted the native storage permission
-5: the media file could not be sent
encodedUrlBase64 encoded media file’s url
Permissions
SendMessage

Example

Ayoba.sendMedia(url, mime);

// Retrieve response Example
  function onMediaSentResponse(responseCode, encodedUrl) {
    var responseCode = responseCode

#Get Country

Ayoba.getCountry()

Gets the user country code in ISO-3166

Parameters
No parameters
Returns
String: user’s ISO-3166 country code. Example: AF
Permissions
Country

Example

 var countryCode = Ayoba.getCountry();

Get Language

Ayoba.getLanguage()

Gets the user language code in ISO-639-1

Parameters
No parameters
Returns
String: the user’s ISO-639-1 language code. Example: en
Permissions
UserLanguage

Example

var languageCode = Ayoba.getLanguage();

Send location

Ayoba.sendLocation(lat, lon)

Sends a location chat message

Parameters
latString: latitude coordinate.
lonString: longitude coordinate

Valid values are decimal numbers with comma or point and integer numbers. Examples: 41.4203 or 41,4203 or 41

Returns
No return value

The following method must be implemented to retrieve the call response:

function onLocationSentResponse(responseCode)

responseCode
1the location has been sent successfully
-1the location could not be sent
Permissions
No permissions required

Example

Ayoba.sendLocation(lat, lon);

// Retrieve response Example

 function onLocationSentResponse(responseCode) {
    var responseCode = responseCode
 }

Retrieve user profile

1. On Nickname Changed

onNicknameChanged(nickname)

Gets the user nickname.

The microapp must implement this method to retrieve the user nickname live data. When data is updated from Ayoba, then Ayoba calls this javascript method on microapp to pass the new data

Parameters
nicknameuser nickname
Returns
No return value
Permissions
UserProfile

Example

    function onNicknameChanged(nickname) {
    currentNickname = nickname
  }


2. On Avatar Changed

onAvatarChanged(avatar)

Gets the user avatar.

The microapp must implement this method to retrieve the user avatar live data. When data is updated from Ayoba, then Ayoba calls this javascript method on microapp to pass the new data

Parameters
nicknameuser nickname
avatarPathuser profile picture URI
Returns
No return value
Permissions
UserProfile

Example

   function onAvatarChanged(avatar) {
    currentAvatarPath = avatarPath
  }

Close MicroApp

Ayoba.finish()

Sends an event to Android to close the MicroApp

Parameters
No parameters
Returns
No return value
Permissions
No permissions required

Example

Ayoba.finish();

Get file

Ayoba.getFile()

Allows the user to choose a file from the device filesystem and retrieves it

Context

Chat and Apps

Parameters

No parameters

Returns

responseCode: response code of accessing the device filesystem 1: the filesystem could be accessed successfully -1: the filesystem could not be accessed

Permissions

FILEACCESS

Example

<script type="text/javascript">
    function getFile() {
        var responseCode = Ayoba.getFile();
        return responseCode;
    }
</script>

The following method must be implemented to retrieve the file, once saved to the app internal storage: onFileRetrievedResponse(responseCode, filePath) Parameters:

responseCode: response code of the file saved to the internal storage 1: the picture has been saved successfully -1: the picture could not be saved

filePath: file’s path

JS retrieve file example:

<script type="text/javascript">
  function onFileRetrievedResponse(responseCode, filePath) {
    var responseCode = responseCode
    var filePath = filePath
  }
</script>
 function getSelfJid() {
        var selfJid = getURLParameter("jid")
        document.getElementById("inputText").value = selfJid
        return selfJid
    }
Parameters
No parameters

Valid values are strings . Examples: 62c3bdfffc5c7c6bb30bc7615beda59537d2d2df@dev.ayoba.me

Returns
String

The following method must be implemented to retrieve the call response:

function getSelfJid()

Permissions
No permissions required

Payment Permissions Accepted

onPaymentPermissionsAccepted(paymentMethodList)

This callback is called when the Ayoba user accepts MicroApp's payment permissions, so the MicroApp can know which payment methods are enabled for the user.

Parameters
paymentMethodListList of enabled payment methods (ie, "MoMo")
Returns
No return value
Permissions
No permissions required

Example

<script type="text/javascript">
    function onPaymentPermissionsAccepted(paymentMethodList) {
        // paymentMethodList is a list containing the enabled payment methods for the user
    }
</script> 

Start a Payment

Ayoba.startPayment(method, amount, currency, description)

Starts a payment transaction.

Parameters
methodString: payment method (ie, "MoMo")
amountNumber: amount of the transaction
currencyString: currency of the transaction (ie, "XAF")
descriptionString: description of the transaction (optional)
Returns
No return value
Permissions
MOMOCOLLECTIONS

EXAMPLE

<script type="text/javascript">
    Ayoba.startPayment("MoMo", 100, "XAF", "Test payment");
</script> 

Payment Status Changed

onPaymentStatusChanged(transactionId, status, error)

This callback is called when a payment transaction status is updated.

Parameters
transactionIdString: Id of the transaction
statusString: String: Status of the transaction: Pending, Success, Failure, Unknown
errorString: Error message: InvalidMicroAppMsidsn InvalidCurrency InvalidPaymentMethod MicroAppUserNotMomoEnabledException MicroAppPendingPaymen tExceptionServerError
Returns
No return value
Permissions
MOMOCOLLECTIONS

EXAMPLE

<script type="text/javascript">
    function onPaymentStatusChanged(transactionId, status, error) {
    }
</script> 

Publish Microapp

In order to publish your App to ayoba, you will need to follow these steps:

  1. Login to the developer portal, this is located in the top right of the screen. If you do not have an account you can sign in via Github or Google.
  2. Click your name in the top right of the portal, and click Profile.
  3. From the profile screen, you will be able to see a list of Apps. You can follow the steps listed there to create a new App.
  4. Follow the steps and await approval

You will require the following:

  • A logo that is 500px × 500px
  • A publically available URL for your application

Authorized Fields

Title: the title of the microapp app displayed to users

Description: More details about the app (if you like)

Category: Choose between the categories shown to help the user find a small app

Developer: Username of the app owner (will be displayed at the bottom of the permissions screen)

Icon: The icon is displayed in the list of microapps

Languages: Languages ​​supported by microapp

Chat URI: The URI used in chat context (Group or P2P), can be used in full screen, intermediate screen and reduced depending on set flags

Countries: Countries where a small app will be available to the user (in both installs and applications)

Microapp permissions

Some permissions are required for the proper functioning of the API. Please find more information below:

Permission types

User Permissions: permissions needed from the user to enable the good funcionning of the micro app

Default permissions: permissions needed and auto accepted without the user consent

Permissions description

MSISDN: user’s phone number

Country: user’s country (from phone number prefix)

Location: user’s location

SendMessage: ability to send text messages and media files on behalf of the user

UserProfile: user’s nickname and profile picture

UserPresence: user’s presence on the microapp (0 or 1)

UserLanguage: user’s language as selected on preferences

Contacts: user’s ayoba contact list