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

Parameters	Type
message	String: 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
lat	Latitude coordinate. Example: 41.4203
lon	Longitude 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
presence	user 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
message	String: 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
responseCode	response code of the opening of the phone’s camera (1: success, -1: failure)
picturePath	picture’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
responseCode	response code of the picture being saved on the external storage (1: success, -1: failure)
picturePath	picture’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
url	String: the media file url
mimeType	String: 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
encodedUrl	Base64 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
lat	String: latitude coordinate.
lon	String: 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
1	the location has been sent successfully
-1	the 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
nickname	user 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
nickname	user nickname
avatarPath	user 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
paymentMethodList	List 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
method	String: payment method (ie, "MoMo, Ozow")
amount	Number: amount of the transaction
currency	String: currency of the transaction (ie, "XAF")
description	String: description of the transaction (optional)

Returns
No return value

Permissions
MoMo
Ozow Pay

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
transactionId	String: Id of the transaction
status	String: String: Status of the transaction: Pending, Success, Failure, Unknown
error	String: 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> 

Start a Payment Overlay

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

Starts a payment overlay transaction.

Parameters
amount	Number: amount of the transaction
currency	String: currency of the transaction (ie, "XAF")
description	String: description of the transaction (optional)

Returns
No return value

Permissions
Use Ayoba Overlay
EXAMPLE

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

Send Generic Event

function sendGenericEvent(eventNumber, description) {
  Ayoba.sendGenericEvent(eventNumber, description);
}

Send a generic event to Firebase Analytics.

Parameters
eventNumber	Number: number of the event, possible values are:
	0: genericEvent1
	1: genericEvent2
	2: genericEvent3
	3: genericEvent4
description	String: description of the event

Returns
No return value

Permissions
No permissions

##Example

<script type="text/javascript">
    Ayoba.sendGenericEvent(1, "Generic Event Number 2"); // This will send an event called "genericEvent2"
</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