Introducing Custom Channels in Conversations

Published on April 27, 2021

At Vonage, we are committed to building the most robust, flexible and scalable platforms possible so that you can continue creating great conversation experiences for your users. With that in mind, we're happy to announce a new sibling for in-app voice and messages channels: Custom Channels!

Using custom events, you can create a custom integration with any channel you can imagine. For example, other messaging platforms, emails, or payments.

How It Works:

1. Defining the `Custom Event` Object

A custom event has a type and a body. The type is your chosen name for the custom channel, which starts with the key "custom:". The body is key-value pairs that define the data you'd like to pass in the event.

2. Sending Custom Events

You can send custom events to a Conversation through Conversations API, or Client SDKs.

When sending an event through the Android or iOS SDKs, the "custom:" prefix for the event type is automatically added on your behalf.

Below are examples of how this can be achieved using the three supported Client SDKs.

Android

var sendListener: NexmoRequestListener<void> = object: NexmoRequestListener<void> {
    override fun onError(error: NexmoApiError) {...}
    override fun onSuccess(var1: Void?) {...}
}

conversation.sendCustomEvent("my_type", hashMapOf("myKey" to "myValue"), sendListener)
</void></void>

iOS

conversation.sendCustom(withEvent: "my_type", data: ["myKey": "myValue"], completionHandler: { (error) in
    if let error = error {...}
    NSLog("Custom event sent.")
})

JavaScript

conversation.sendCustomEvent({ type: 'custom:my_type', body: { myKey: 'myValue' }}).then((custom_event) => { ... });

3. Receiving Custom Events

Receiving a custom event is similar to receiving any other event in you’ll receive it on your application's RTC event_url.

In our three supported Client SDKs, you'll receive it as shown below:

Android

var customEventListener: NexmoCustomEventListener = NexmoCustomEventListener { event ->
    Log.d(TAG, "Received custom event with type " + event.customType + ": " + event.data)
}

conversation.addCustomEventListener(customEventListener)

iOS

//In `NXMConversationDelegate`:

func conversation(_ conversation: NXMConversation, didReceive event: NXMCustomEvent) {
    NSLog("Received custom event with type \(String(describing: event.customType)): \(String(describing: event.data))");
}

JavaScript

conversation.on('custom:my_type', (from, event) => {
  console.log(event.body);
});

4. Sending Push Notifications

If your Android or iOS application is running in the background, you might want to notify your user about an incoming custom event with a push notification.

To do that, you must define the payload to send per push notification on a per type basis:

PUT https://api.nexmo.com/v2/applications/:your_nexmo_application_id

{
	"capabilities": {
		"rtc": {
			...
			"push_notifications": {
				"custom:my_type": {
					enabled: true,
					template: {
						notification: {
						body: "Value sent: '${event.body.my_key}' !”
					},
					data: {
						image: "https://example.image.jpg",
                                                myKey: myValue
					}
				}
			}
		}
	}
}

5. Receiving Push Notification

After setting up push notifications for your mobile apps, you’re ready to receive your custom push. You can access the custom data that you previously defined as follows:

Android

if (NexmoClient.isNexmoPushNotification(message!!.data)) {  
    NexmoPushPayload nexmoPushPayload = nexmoClient.processPushPayload(message!!.data, pushListener)
    when(nexmoPushPayload.pushTemplate){
        Custom ->
            nexmoPushEvent.customData //got custom push data 😀
        Default ->
            nexmoPushEvent.eventData // got default push event data
    }
}

iOS

NSDictionary* pushData = [get the payload];
 
if ([NXMClient.shared.isNexmoPush:pushData]) {
    NXMPushPayload nexmoPushPayload = [NXMClient.shared processPushPayload:pushData];
  
    if (nexmoPushPayload.template == NXMPushTemplateCustom){
        nexmoPushEvent.customData //got custom push data 😀
    }
    if (nexmoPushPayload.template == NXMPushTemplateDefault){
        nexmoPushEvent.eventData // got default push event data
    }
}

Integration Complete

You now have all you need to a custom channel with custom push notifications into your conversation experiences. We can't wait to see which channels you’ll add and how you'll use them to enrich your user's conversation with you!

What's Next?

Check out the full guides custom events guides for Conversations API and for Client SDKs.
Find examples for custom channel integrations with WeChat, SendinBlue emails, or payments with Stripe.
Explore more Conversations API and Client SDK features in our public documentation.

Should you have any questions or feedback - let us know on our Community Slack or support@nexmo.com