Develop calling and online meeting bots on your local PC
In Run and debug your app, we explain how to use ngrok to create a tunnel between your local computer and the internet. In this topic, learn how you can also use ngrok and your local PC to develop bots that support calls and online meetings.
Messaging bots use HTTP, but calls and online meeting bots use the lower-level TCP. Ngrok supports TCP tunnels in addition to HTTP tunnels.
Configure ngrok.yml
Go to ngrok and sign up for a free account or log into your existing account. After you've signed in, go to the dashboard and get your auth token.
Create a ngrok configuration file ngrok.yml
and add the following line. For more information on where the file can be located, see ngrok:
authtoken: <Your-AuthToken>
Set up signaling
In Calls and online meetings bots, we discussed call signaling on how bots detect and respond to new calls and events during a call. Call signaling events are sent through HTTP POST to the bot's calling endpoint.
As with the bot's messaging API, for the Real-time Media Platform to talk to your bot, your bot must be reachable over the internet. Ngrok makes this simple. Add the following lines to your ngrok.yml:
tunnels:
signaling:
addr: 12345
proto: http
Set up local media
Note
This section is only required for application-hosted media bots and can be skipped if you don't host media yourself.
Application-hosted media uses certificates and TCP tunnels. The following steps are required:
Ngrok's public TCP endpoints have fixed URLs. They're
0.tcp.ngrok.io
,1.tcp.ngrok.io
, and so on. You must have a DNS CNAME entry for your service that points to these URLs. For example, let's say0.bot.contoso.com
refers to0.tcp.ngrok.io
,1.bot.contoso.com
refers to1.tcp.ngrok.io
, and so on.An SSL certificate is required for your URLs. To make it easy, use an SSL certificate issued to a wild card domain. In this case, it would be
*.bot.contoso.com
. This SSL certificate is validated by the media SDK, so it must match your bot's public URL. Note the thumbprint and install it in your machine certificates.Now, set up a TCP tunnel to forward the traffic to localhost. Write the following lines into your ngrok.yml:
media: addr: 8445 proto: tcp
Start ngrok
Now that the ngrok configuration is ready, launch it:
ngrok.exe start -all -config <Path to your ngrok.yml>
This starts ngrok and defines the public URLs, which provide the tunnels to your localhost. Following is an example of the output:
Forwarding http://signal.ngrok.io -> localhost:12345
Forwarding https://signal.ngrok.io -> localhost:12345
Forwarding tcp://1.tcp.ngrok.io:12332 -> localhost:8445
Here, 12345
is the signaling port, 8445
is the application-hosted port, and 12332
is the remote media port exposed by ngrok. Note that we have a forwarding from 1.bot.contoso.com
to 1.tcp.ngrok.io
. This is used as the media URL for the bot. Of course, these port numbers are just examples and you can use any available port.
Update code
After ngrok is up and running, update the code to use the config you just set up.
Update signaling
In the BotBuilder call, change the NotificationUrl
to the signaling URL provided by ngrok.
statefulClientBuilder.SetNotificationUrl(
new Uri("https://signal.ngrok.io/notificationEndpoint"))
Note
Replace signal with the one provided by ngrok and the NotificationEndpoint
with the controller path that receives notification.
Important
- The URL in
SetNotificationUrl
must be HTTPS.
Your local instance must be listening to HTTP traffic on the signaling port. The requests made by the calls and online meetings platform reach the bot as localhost HTTP traffic unless end-to-end encryption is set up.
Update media
Update your MediaPlatformSettings
as following:
var mediaPlatform = new MediaPlatformSettings
{
ApplicationId = <Your application id>
MediaPlatformInstanceSettings = new MediaPlatformInstanceSettings
{
CertificateThumbprint = <Your SSL Cert thumbprint>,
InstanceInternalPort = <Localhost media port>,
InstancePublicPort = <Ngrok exposed remote media port>,
InstancePublicIPAddress = new IPAddress(0x0),
ServiceFqdn = <Media url for bot (eg: 1.bot.contoso.com)>,
},
}
Note
The certificate thumbprint provided in the MediaPlatformSettings
must match the Service FQDN. That is why the DNS entries are required.
Caveats
- Ngrok free accounts don't provide end-to-end encryption. The HTTPS data ends at the ngrok URL and the data flows unencrypted from ngrok to
localhost
. If you require end-to-end encryption, consider a paid ngrok account. See TLS tunnels for steps on setting up secure end-to-end tunnels. - Because the bot callback URL is dynamic, incoming call scenarios require you to frequently update your ngrok endpoints. One way to fix this is to use a paid ngrok account, which provides fixed subdomains to which you can point your bot and the platform.
- Ngrok tunnels can also be used with Azure Service Fabric. For an example of how to do this, see the HueBot sample app.
See also
Platform Docs