The Messenger API, our original messages endpoint, delivers personalized notifications about upcoming goals. Its purpose is to remind users of how much time they have left to complete their next game goal. These timely messages motivate players to stay active, helping them earn rewards and stay engaged.
Preparing to connect
Follow these steps to prepare to connect to Besitos APIs:
Have your partner ID ready.
Contact your Besitos Account Manager to request API access.
Generate and save your bearer token for authentication.
Continue reading for a complete description of the API parameters and response attributes, or visit our Postman collection to start testing.
Endpoint
Endpoint URL | https://wall.besitos.ai/data/messages/{partner_id}/upcoming-goals |
HTTP method | POST |
Path parameter
Path parameter | Data type | Required | Description |
| string | yes | Your Besitos partner ID. |
Supported filters
To filter the response, you can include optional POST parameters in the request body. Here are some examples of how and why you might use these parameters:
Return messages related to goals for users whose IDs you include in the subscribers parameter
Return messages for goals with the hours specified in the hours_from and hours_to parameters
Return messages for specific offers with the offers parameter
The entire dataset will be returned if you do not use these parameters.
Parameter | Data type | Required | Description and example |
| array | no | Returns all goals for each user ID you include in the array. If you do not include a user ID(s), all available goals for every user on your account will be returned. Example: 21sdf1sef54wef64 |
| array | no | Returns all goals for each offer ID included in the array. If you do not include any offer ID(s), all goals for all offers in your account will be returned. Example: rYZv23fgqfSN |
| integer | no | Returns all goals for each offer ID included in the array. If you do not include any offer ID(s), all goals for every offer in your account will be returned. Example: 10 |
| integer | no | This value marks the end of a range that returns all goals with the specified hours remaining. If you do not specify a number, all goals with up to 48 hours remaining will be returned. Example: 41 |
| string | no | With this filter, you can modify the following message variables: hours, level, game, and reward. If you omit the "message_template," the default message will be returned.
Example of default message: Reminder: You have [#] hours left to reach [level] of [game] and earn [reward]. Don’t miss the deadline.
|
Examples
Request
Request
$apiUrl = 'https://wall.besitos.ai/data/messages/{partnerID}/upcoming-goals';
$accessToken = 'your_bearer_access_token';
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => $apiUrl,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"subscribers": [
"LaQ1VYb5ANTAny25Ig",
"21sdf1sef54wef64"
],
"offers": [
"rYZvzXlCqfSN",
"rYZv23fgqfSN"
],
"hours_from": 24,
"hours_to": 120,
"message_template":"You have {hours} hours left to reach {level} of {game} and earn {reward}. Don\'t miss the deadline."
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'Authorization: Bearer ' . $accessToken
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;Response
Response
{
"current_page": 1,
"data": [
{
"subscriber_id": "LaQ1VYb5ANTAny25Ig",
"game": "Alice‘s Dream : Merge Island",
"level": "level 1079",
"level_description": "Reach Level 15",
"hours": 3,
"currency": "coins",
"reward": "40 coins",
"message": "You have 3 hours left to reach level 1079 of Alice‘s Dream : Merge Island and earn 40 coins. Don't miss the deadline."
},
{
"subscriber_id": "LaQ1VYb5ANTAny25Ig",
"game": "Alice‘s Dream : Merge Island",
"level": "level 1081",
"level_description": "Reach Level 20",
"hours": 291,
"currency": "coins",
"reward": "80 coins",
"message": "You have 291 hours left to reach level 1081 of Alice‘s Dream : Merge Island and earn 80 coins. Don't miss the deadline."
}
],
"first_page_url": "http://besitos-service.test/data/messages/eafLst9T/upcoming-goals?page=1",
"from": 1,
"next_page_url": null,
"path": "http://besitos-service.test/data/messages/eafLst9T/upcoming-goals",
"per_page": "2",
"prev_page_url": null,
"to": 2
}
Response attributes
Attributes | Type | Description | Example |
| string | The unique identifier of the user. |
|
| string | The name of the game. |
|
| string | The current or target level (contains text and number). |
|
| string | A description of the goal in the offer. |
|
| integer | Hours remaining to achieve the goal, calculated from the “install” goal; the countdown begins once a user installs the game app. |
|
| string | Your (partner) currency (points, dollars, etc.). |
|
| string | The user’s reward for reaching the upcoming goal. |
|
| string | The message for the upcoming goal. |
|
For help, contact your Besitos Account Manager or our Implementation Team at [email protected] or via your project channel in Slack.