Mesibo Real-time Push Notification

Estimated reading time: 16 minutes

mesibo allows you to send push notifications to your users without using any external services. mesibo sends a push notification when there is a new message or calls for one of your users, and the user is offline. When the offline user receives a push notification, the device wakes up and starts receiving messages and calls.

Configuring Push Notifications

mesibo automates the entire push notification handling for you without any intervention from your end. All you need to do is to

  1. Configure your Apple APN and Google FCM push credentials in the mesibo console. This is a one-time process for your entire app.
  2. Configure Push Settings and Push Notification Type in the mesibo console.
  3. Code your apps to use Apple or Android FCM push notifications and send the push token to mesibo for each user.

That’s it! mesibo will now automatically send a push notification when the destination user is offline.

Push Notification Types

Before we describe how to configure your Push credentials, it is important to understand the type of notifications (visible and invisible) so that you can appropriately configure them. There are two types of push notifications:

1. Background Notifications (Invisible, Default)

This type of notifications are NOT visible (data type in Android and background or VoIP type in iOS). They do not show visible notifications or play any sound.

By default, mesibo sends background notifications that wake up or launch your app in the background. Your app can then start mesibo to receive all the messages and calls. Once your app receives messages, it can then use local notification to show the notification. This is a recommended way of receiving push for real-time applications as it gives you the finer control over when and what to show in the notification including any localization. However, you can change this default behavior from the mesibo console by disabling the Background push checkbox. It will then send visible push alerts.

2. Alert Notifications (Visible)

These are visible alerts (notification type in Android and alert type in iOS). Although it is tempting to use them, they do not offer finer control and don’t always wake up your app. Hence, we do not recommend using it.

It is highly recommended that you refer to the mesibo messenger app source code to see how it is implemented there.

Now let’s set up push credentials in the mesibo console.

Setting up Push notification Credentials in mesibo Console

To enable mesibo to send push notifications to your users, you need to configure push notification credentials in the mesibo console.

Follow the steps below to configure your push notification credentials.

Configure FCM Credentials for Android Notifications

  1. Go to your App settings in the mesibo console. Go to the section Push Notifications and turn ON the switch to enable push notifications. Now, enter the necessary details in Android - Firebase Cloud Messaging (FCM) Configuration
  2. Get the Firebase Sender ID and Firebase Server Key from Firebase Console of your app. Enter it in the mesibo console. Refer to the Firebase Documentation and FCM Messages for setting up your FCM Server.
  3. Enter the credentials that you got- Firebase Sender ID and Firebase Server Key in - Firebase Cloud Messaging (FCM) Configuration section.
  4. Under push, settings select Background Push (recommended) or set your required push notification type.

Configure APN/VoIP Credentials for iOS Notifications

  1. Go to your App settings in the mesibo console. Go to the section Push Notifications and turn ON the switch to enable push notifications. Now, enter the necessary details in Apple Push Notification (APN) Configuration
  2. Get the universal Push/VoIP certificate in .p12 format from your Apple Developer Account. Refer to Obtain a Provider Certificate from Apple
  3. Choose the universal Push/VoIP certificate file that you downloaded earlier and upload it in the Apple Push Notification (APN) Configuration section.
  4. Under push, settings select Background Push (recommended) or set your required push notification type.

Use the Production Certificate, not the development certificate. Mesibo console will give you a warning but will accept the certificate. However, your device is likely not to receive push notifications.

Push Settings

You can configure additional push notification settings in the mesibo console.

  • Background Push, By default, mesibo will send ‘Background Push’, which is recommended. However, you can change it to alert by disabling the ‘Background Push’ checkbox.

  • Sound, Play a notification sound to alert the user. You can enable this only if you have disabled background push(silent push)

  • Collapse Notifications, Check this box to group multiple notifications and make them collapsible.

  • Send Sandbox Push to APN Production server, If you want all your push requests to go to the production APN server even while using a development environment, enable this option. For more information, refer to the Troubleshooting section.

  • Autoroute iOS Push through APN or FCM, If you have configured FCM credentials and would like to route iOS push through FCM, check this option.

  • Print Push Logs, If you are using on-premise, check this to enable Debug Logs. You can then see logs in the on-premise server logs for every push request sent to FCM or APN and the result. If you are using mesibo cloud, see Debugging Push Notifications using Webhooks

Preparing your App to receive Push Notifications

Once you set up the above information in the mesibo console, mesibo is almost ready to send push notifications to your users. However, you still need to prepare your app to receive and process push notifications. You need to ensure that your app can process push notifications quickly and can perform the following tasks.

  1. Initialize mesibo on receiving a push
  2. Use local notifications to show customized notifications
  3. Send device token to mesibo

1. Initialize mesibo on receiving a push

When your app receives a push notification, the system launches your app or wakes it from the suspended state. If you have already initialized mesibo, and when the system wakes your app from the suspended state, mesibo will connect automatically. However, if the system launches your app on receiving push, your app MUST ensure that mesibo is initialized quickly before the system suspends your app.

Refer to the Android and iOS messenger source code to learn how messenger initialized mesibo on receiving a push.

2. Use local notifications to show customized notifications

As explained earlier in the section Push Notification Types, by default mesibo sends a background push notification (recommended). Background notifications are not visible and hence you should use local notifications to show the notifications. Local notifications give you complete control over how notification will look and any localization, if requires.

Refer to the Android and iOS messenger source code to learn how messenger users local notifications to show notifications.

3. Send device token to mesibo

mesibo requires a unique token per user so that it can send push notifications to that particular user. You need to obtain that user-specific device token using Android or iOS API and then send it to mesibo using setPushToken() API.

Sending push notification token in Android

  1. To understand how to get the user push token, refer to Firebase Docs, Or this detailed tutorial on Android Push Notifications

  2. Use Mesibo setPushtoken() API to send push token to mesibo.

Refer to the Messenger App Source code for Android, which uses setPushtoken API

Sending push notification token in iOS

Unlike Android, iOS has two separate tokens, one for push and one for VoIP (PushKit). You only need to use the push token.

  1. Refer APN Docs or this detailed tutorial on iOS Push Notifications

  2. Use Mesibo setPushtoken() API to send push token to mesibo.

Refer to the Messenger App Source code for iOS, which uses setPushtoken API

Troubleshooting

General Troubleshooting

If your app doesn’t get the push, check the following:

  • Ensure that you are testing push notifications under normal conditions. Your app will not receive push if you force stop the app, clean app cache, etc.
  • Ensure that you have configured push-notification credentials for your app correctly on the mesibo console.
  • Ensure that your phone is not in Do-Not-Disturb mode.
  • Keep your phone on the cellular data and see if you are receiving push notifications.
  • See if other apps on your phone receive it.
  • mesibo will only send push when your app is suspended and disconnected. It may take a few seconds (or minutes) depending on the operating system and also the device configuration.

Additional Troubleshooting Steps for iOS

  • While PushKit is ideal for calls, the iOS 13 and newer mandatorily require CallKit integration and reporting when using Push Tokens which does not go well with Video Calls. If not, iOS will terminate your app. Refer to Apple documentation and WWDC talk Advances in App Background Execution. Also, according to these threads (here, here, and here), only a few apps (WhatsApp, FB messenger, Telegram) are given special privileges, so unless your app is also given those privileges, we currently do not recommend using Push Kit.
  • Use the Production Certificate, not the development certificate. Mesibo console will give you a warning but will accept the certificate. However, your device is likely not to receive push notifications.
  • Ensure that the bundle ID on the certificate matches your app bundle ID. Note, if you are using the mesibo demo app, you need to change the bundle ID to match your certificate.
  • Don’t mess with the APS entitlements setting unless you know what you are doing. By default, it is set to development for the development and set to Production by Xcode when you upload your app to the App Store for release or test flight. This setting impacts the selected APN endpoint for sending push notifications. Hence, if you change this to say ‘Production’, you may need to send all your sandbox pushes to the production APN server

Troubleshooting using Custom Scripts

Another troubleshooting option is to send a push notification yourself and see if it helps. Use one of the scripts below to send push notifications to your device. Once it is working, you can set up the mesibo webhook, which will be invoked when the destination is offline. You can then send push notifications from the webhook using your custom scripts. You can also use webhooks to inspect the push request sent by mesibo and the response received from FCM/APN. See Debugging Push Notifications using Webhooks.

Use the following PHP script to send push notifications to Android devices.

<?php

function android_push($to) {
	$apiKey = 'FCM API KEY';
	$url = 'https://fcm.googleapis.com/fcm/send';

	$priority = "high"; 
	$type = "data"; // or 'notification' . 

	$message = "none"; // your message
	$topic = ''; // not using, https://developers.google.com/cloud-messaging/topic-messaging
	$collapse_key = 'NEWMESSAGE'; 

	// there are two kinds of messages, data (default priority normal) and notification (default priority high). 
	$fields = array(
			'to' => $to,
			'priority' => $priority,
			'collapse_key' => $collapse_key,
			$type => array( "message" => $message ),
		       );

	$headers = array(
			'Authorization: key=' . $apiKey,
			'Content-Type: application/json'
			);

	// Open connection
	$ch = curl_init();

	// Set the URL, number of POST vars, POST data
	curl_setopt( $ch, CURLOPT_URL, $url);
	curl_setopt( $ch, CURLOPT_POST, true);
	curl_setopt( $ch, CURLOPT_HTTPHEADER, $headers);
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
	curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode( $fields));

	// Execute post
	$result = curl_exec($ch);

	// Close connection
	curl_close($ch);

	$r = json_decode($result, 1);
	if(isset($r['failure']) && $r['failure'] > 0) {
		print_r($r);
		return false;
	}

	return true;
}

Use the following PHP script to send push notifications to iOS devices.

<?php
$token = "Client Token";

// APN certificate
$certificate = 'universal_cert.pem';

$alert_message = '{"aps":{"action":"message","title":"your_title","body":"your_message_body"}}';
$message = '{"aps":{"content-available":"1"}}';
$apn_server = 'https://api.development.push.apple.com'; // or 'api.push.apple.com' if production

// change this to match your certificate and app bundle id
$bundle_id = 'com.mesibo.app';

$status = apn_push(true, "background", $apn_server, $certificate, $bundle_id, $message, $token);
echo $status;

//type can be alert,voip, etc. Refer to APN documentation
function apn_push($production, $type, $apn_server, $certificate, $bundle_id, $message, $token) {

	$apn_server = 'https://api.development.push.apple.com';
	if($production) {
		$apn_server = 'https://api.push.apple.com';
	}


	$url = "{$apn_server}/3/device/{$token}";
	$cert = realpath($certificate);
	
	// headers
	$headers = array(
		"apns-topic: {$bundle_id}",
		"User-Agent: mesibo",
		"apns-push-type: {$type}",
		"apns-priority: 5",
	);

	// open connection 
	$ch = curl_init();

	curl_setopt_array($ch, array(
		CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_2_0,
		CURLOPT_URL => $url,
		CURLOPT_PORT => 443,
		CURLOPT_HTTPHEADER => $headers,
		CURLOPT_POST => TRUE,
		CURLOPT_POSTFIELDS => $message,
		CURLOPT_RETURNTRANSFER => TRUE,
		CURLOPT_TIMEOUT => 30,
		CURLOPT_SSL_VERIFYPEER => false,
		CURLOPT_SSLCERT => $cert,
		CURLOPT_HEADER => 1,
		CURLOPT_RETURNTRANSFER =>true
	));

	$result = curl_exec($ch);
	if ($result === FALSE) {
		$error = curl_error($ch);
		echo "curl faild: $error";
		curl_close($ch);
		return false;
	}

	// get response
	$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
	curl_close($ch);
	if($status == "200")
		echo "OK";
	else
		echo "FAIL: $status";

	return false;

}

Troubleshooting using Webhooks

If your app cannot receive push notifications, even after troubleshooting with the steps above, you can also debug the issue with push notifications using webhooks.

You can inspect the push request and response, which can be made available to you through webhooks. To do this, check Notify failed push notifications while setting up Webhook, in the console. When a push notification fails, you will receive a webhook request( a POST request) from mesibo, and the payload will contain information about the push event. In the webhook payload, you can inspect the request and the response so that you can understand the reason for failure or why the push service(FCM/APN) rejected the push. For example, if you did not configure the right credentials, etc.

Refer mesibo Real-time webhooks to know about setting up a webhook and using the push event type to debug failed push notifications.

In the push event, the response.code field will contain the error code which indicates the reason for failure.

If FCM/APN rejected the push, then refer to respective documentation of push notification error codes.

  • For FCM, refer here
  • For APN, refer here

If Mesibo rejected the push, then the error code will be a value greater than 900. Refer to the table below for special error codes and their meaning:

Error Code Description
901 Push service for the app is not configured
901 Push service for the app is temporarily disabled
903 Push certificate expired
904 Push certificate error
905 Production certificate is required for this push
911 Bad push token
912 Mismatch in APN certificate and the push token app id
913 Bad payload
mesibo, android, ios