## MSISDN
---
This is where you will find all the documentation related to our MSISDN APIs.

## Get MSISDN
---
Gets the user phone number

```js
Ayoba.getMsisdn()
``` 
#### Example
---
```js  
function getMsisdn() {
    var msisdn = Ayoba.getMsisdn();
    return msisdn
 }
```
---
| Parameters | No parameters |
| ---------- |---------- |
| Returns | String: the user’s MSISDN. Example: +93777777778 |
| Permissions | MSISDN |


## Get SelfJid
---
#### Example
```js
 function getSelfJid() {
     var selfJid = getURLParameter("jid")
     document.getElementById("inputText").value = selfJid
     return selfJid
 }
```
---
| Parameters | No parameters |
| ---------- |---------- |
| Returns |String. Examples: **62c3bdfffc5c7c6bb30bc7615beda59537d2d2df@dev.ayoba.me**|
| Permissions |No permissions required |

---
The following method must be implemented to retrieve the call response:
```js
function getSelfJid()
```


## Compose message
---
Puts a text on the compose bar of the chat screen without sending the message
```js
Ayoba.composeMessage(message); 
```
#### Example
---
```js
Ayoba.composeMessage(message);
```
---
| Parameters | %message $String: message to put on the compose bar | 
| ------------- | :-------------: |
| Returns | No return value |
| Permissions |No permissions required|


## Send message
---
Sends a chat message directly without putting the text on the compose bar of the chat screen
```js
Ayoba.sendMessage(message)
```
---
#### Example
---
```js
Ayoba.sendMessage(message);
```
---
| Parameters| %message $String: message to send directly |
| ---------------- | :------------: |
| Returns | No return value |
| Permissions | SendMessage |

## Get Send Message
---
Returns true if the user has accepted the permission to send a message.
```js
Ayoba.getCanSendMessage()
```
#### Example
---
```js
Ayoba.getCanSendMessage()
```
---

| 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 |

## Start Conversation
---
Sends an event to Ayoba application to start conversation on the service.
```js
ayoba.startConversation(jid);
 ```
 
 #### Example
 ---
```js
string jid = "62c3bdfffc5c7c3bb30bc7beda52531d2d2df@dev.ayoba.me";
function startConversation() {
   ayoba.startConversation(jid);
  }
```
---
| Parameters | jid | 
| ------------- | ------------- |
| Returns | No return value | 
| Permissions | No permissions required | 

## Get country
---
Gets the user country code in ISO-3166
```js
Ayoba.getCountry()
```

#### Example
---
```js
 var countryCode = Ayoba.getCountry();
```
---

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

## Get User Location
---
Gets the user location.
The service must implement this method to retrieve the location live data. When data is updated from Ayoba, then Ayoba calls this javascript method on service to pass the new data

```javascript
onLocationChanged(lat, lon)
```

#### Example
---
```javascript
  function onLocationChanged(lat, lon) {
    currentLatitude = lat
    currentLongitude = lon
  }
```
---
| Parameters |  %lat  $Latitude coordinate. Example: 41.4203 %lon $Longitude coordinate. Example: 2.1828 |
| -------------- | :--------: |
| Returns | No return value |
| Permissions | Location |

## Send location
---
Sends a location chat message
```javascript
Ayoba.sendLocation(lat, lon)
```
#### Example
---
```javascript
Ayoba.sendLocation(lat, lon);

// Retrieve response Example

 function onLocationSentResponse(responseCode) {
    var responseCode = responseCode
 }
```
---
| Parameters | %lat  $String: latitude coordinate. %lon $String: longitude coordinate |
| --------------- | :-----------: |
| Returns | No return value |
| Permissions | Location |
----

The following method must be implemented to retrieve the call response:
```javascript
function onLocationSentResponse(responseCode)
```
#### Example
---
```javascript
Ayoba.sendLocation(lat, lon);

// Retrieve response Example

 function onLocationSentResponse(responseCode) {
    var responseCode = responseCode
 }
```
| Parameters |   responseCode|
| ------------------ | :------------: |
|responseCode| %1  $the location has been sent successfully %-1  $the location could not be sent |
| Returns | No return value |
| Permissions | No permissions required |


## Get File
---
It allows the user to choose a file from the device's filesystem and retrieve it.
```js
Ayoba.getFile()
```
#### Example
---
```js
<script type="text/javascript">
    function getFile() {
        var responseCode = Ayoba.getFile();
        return responseCode;
    }
</script>
```
---
|Context|Chat and Services|
|--------|--------------|
|Parameters|No parameters|
|Returns| %responseCode $response code of accessing the device filesystem|
|responseCode| %1 $the filesystem could be accessed successfully %-1 $the filesystem could not be accessed|
|Permissions|FILEACCESS|

## Get File Save to Internal Storage
---
The following method must be implemented to retrieve the file once it is saved to the service's internal storage:
```js
onFileRetrievedResponse(responseCode, filePath)
```
#### Example
---
```js
<script type="text/javascript">
  function onFileRetrievedResponse(responseCode, filePath) {
    var responseCode = responseCode
    var filePath = filePath
  }
</script>
```
---
|Parameters| %responseCode $response code of the file saved to the internal storage %filePath $file’s path|
|responseCode| %1 $the picture has been saved successfully %-1 $the picture could not be saved|


## Take and retrieve picture
---
Takes a picture with the phone’s camera.
```js
Ayoba.takePicture();
```
## Example
---
```js
function takePicture() {
    Ayoba.takePicture();
}
```
| Parameters | No parameters |
| -------------- | -------------- |
| Returns | %responseCode $ response code of the opening of the phone’s camera |
|responseCode| %1: $success, %-1 $failure|
| Permissions |TAKEPHOTO |

## Gets the response code and path of the picture taken.
---
The service must implement this method to retrieve the picture taken's path. When data is updated from Ayoba, then Ayoba calls this javascript method on service to pass the new data

```js
onPictureRetrievedResponse(responseCode, picturePath);
```

#### Example
```js  
function onPictureRetrievedResponse(responseCode, picturePath) {
    var responseCode = responseCode
    var picturePath = picturePath
}
```
| Parameters	| %responseCode $response code of the picture being saved on the external storage %picturePath $picture’s path |
| -------------- | :------------: |
|responseCode| %1 $success, %-1 $failure|
| Returns | No return value |
| Permissions |TAKEPHOTO |

## Send media
---
Sends a media chat message (image, video, audio, file or contact)
```js
Ayoba.sendMedia(url, mimeType)
```
#### Example
---
```js    
Ayoba.sendMedia(url, mime);

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

| Parameters	|  %url $String: the media file url  %mimeType	$String: the mime type of the media file   |
|--------------|----------------------------------------------------------------------------------------|
|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 |
| Permissions| SendMessage |

The following method must be implemented to retrieve the call response:
```js
function onMediaSentResponse(responseCode, encodedUrl)
```
| Parameters |responseCode %encodedUrl $Base64 encoded media file’s url |
| ---------------- | :------------------: |	
|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 |
| Permissions| SendMessage |

## Get user presence
---
Gets the user presence.
The service must implement this method to retrieve the user presence live data. When data is updated from ayoba, then ayoba calls this javascript method on service to pass the new data
```javascript
onPresenceChanged(presence)
```

#### Example
---
```js
function onPresenceChanged(presence) {
    currentPresence = presence
  }
```

| Parameters | presence |
| ------------| :---------------------------: |
| presence	| %0 $Offline %1 $Online |
| Returns | No return value |
| Permissions |UserPresence |

## Get user profile
---
### 1. On Nickname Changed
---
Gets the user nickname.
The service must implement this method to retrieve the user nickname live data. When data is updated from ayoba, then ayoba calls this javascript method on service to pass the new data
#### Example
----
```js
    function onNicknameChanged(nickname) {
    currentNickname = nickname
  }
```
| Parameters	|nickname|
| ------------- | :--------- |
| Returns | No return value |
| Permissions | UserProfile |

### 2. On Avatar Changed
---
Gets the user avatar.
The service must implement this method to retrieve the user avatar live data. When data is updated from ayoba, then ayoba calls this javascript method on service to pass the new data
```javascript
onAvatarChanged(avatar)
```

#### Example
---
```js
   function onAvatarChanged(avatar) {
    currentAvatarPath = avatarPath
  }
```

| Parameters	|%nickname $user nickname  %avatarPath  $user profile picture URI |
| --------------- | :---------------------------------------------------------------- |
| Returns | No return value |
| Permissions | UserProfile |

## Get language
---
Gets the user language code in ISO-639-1
 ```js
Ayoba.getLanguage()
```
#### Example
---
```js  
var languageCode = Ayoba.getLanguage();
```
---
| Parameters | No parameters |
| -------------- | ---------------- |
| Returns | String: the user’s ISO-639-1 language code. Example: en |
| Permissions | UserLanguage |

## Send Generic Event
---
Send a generic event to Firebase Analytics.

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

#### Example
---
```js

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

```

 Parameters	| %eventNumber $ ***Number:*** number of the event, possible values are: %description $***String:*** description of the event |
| ---------- | :--------------------------------------------------------------------- |
| eventNumber | %0: $genericEvent1 %1: $genericEvent2 %2: $genericEvent3 %3: $genericEvent4 |
| Returns | No return value |
| Permissions | No permissions |


## Start a Payment
---
Starts a payment transaction.
```js
Ayoba.startPayment(method, amount, currency, description)
```
#### Example 
---
```js
<script type="text/javascript">
    Ayoba.startPayment("MoMo", 100, "XAF", "Test payment");
</script> 
```
| Parameters | %method $***String:*** payment method (ie, "MoMo") %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 | MOMOCOLLECTIONS |


## Payment Permissions Accepted
---
This callback is called when the ayoba user accepts service's payment permissions, so the service can know which payment methods are enabled for the user.

```js
onPaymentPermissionsAccepted(paymentMethodList)
```
#### Example 
---
```js
<script type="text/javascript">
    function onPaymentPermissionsAccepted(paymentMethodList) {
        // paymentMethodList is a list containing the enabled payment methods for the user
    }
</script> 
```
| Parameters | %paymentMethodList  $List of enabled payment methods (ie, "MoMo") |
| -------------- | :--------: |
| Returns | No return value | 
| Permissions | No permissions required |


## Payment Status Changed
---
This callback is called when a payment transaction status is updated.
```javascript
onPaymentStatusChanged(transactionId, status, error)
```
#### Example
---
```js
<script type="text/javascript">
    function onPaymentStatusChanged(transactionId, status, error) {
    }
</script> 
```
| 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 |

Documents

Get user presence

Example

Get user profile

1. On Nickname Changed

Example

2. On Avatar Changed

Example

Get language

Example

Send Generic Event

Example

Next Steps