Stream call events to NATS

What you’ll build

You run Routr and a NATS server with Docker Compose, turn on EdgePort’s NATS publisher, and subscribe to the events with the nats CLI. When you register two softphones and call between them, you see routr.endpoint.registered, routr.call.started, and routr.call.ended messages arrive. Call events come from EdgePort, so you can feed them to billing, dashboards, or any service that speaks NATS without touching the SIP path.

Prerequisites

Docker with Docker Compose
The nats CLI
Node.js and npm, to install rctl
Two SIP softphones
The IP address of your machine on your local network (for example, 192.168.1.3)

Steps

Define the services

Create a folder for the tutorial and a compose.yaml file inside it. It runs a NATS server and routr-one with the NATS publisher turned on.Filename: compose.yaml

services:
  nats:
    image: nats:latest
    ports:
      - 4222:4222

  routr:
    image: fonoster/routr-one:latest
    depends_on:
      - nats
    environment:
      EXTERNAL_ADDRS: ${DOCKER_HOST_ADDRESS}
      NATS_PUBLISHER_ENABLED: "true"
      NATS_PUBLISHER_URL: nats://nats:4222
    ports:
      - 51908:51908
      - 5060:5060
      - 5060:5060/udp

EdgePort reads three variables:

Variable	Purpose	Default
`NATS_PUBLISHER_ENABLED`	Set to `true` to publish events	Off
`NATS_PUBLISHER_URL`	NATS server to connect to	`nats://localhost:4222`
`NATS_PUBLISHER_SUBJECT`	Prefix for every subject	`routr`

Start the stack

Start the services. Replace the address with your own.

DOCKER_HOST_ADDRESS=192.168.1.3 docker compose up -d

Confirm that EdgePort connected to NATS.

docker compose logs routr | grep "nats publisher"

The output includes a line that ends like this:

GRPCSipListener.java nats publisher enabled with subject routr and url nats://nats:4222

The log line above appears, and the routr container stays up.

Subscribe to Routr events

Create a nats CLI context for the local server and select it.

nats context add local --server nats://localhost:4222 --description "Routr events" --select

Subscribe to every subject under routr. Leave this running.

nats sub "routr.>"

Subscribing on routr.>

Create a Domain and two Agents

In another terminal, install rctl.

npm install --location=global @routr/ctl

Create a Domain with the SIP URI sip.local.

rctl domains create --insecure

Create credentials and an Agent for 1001, then repeat for 1002. Pick the Domain sip.local and the matching credentials when rctl agents create asks.

rctl credentials create --insecure
rctl agents create --insecure

The --insecure flag is required because this setup doesn’t use TLS on the API.

Configure each softphone with one Agent: its username and password, sip.local as the domain, and your machine’s IP (for example, 192.168.1.3:5060) as the outbound proxy over UDP.Each successful registration publishes an event.

[#1] Received on "routr.endpoint.registered"
{"aor":"sip:1001@sip.local","registeredAt":"2026-10-21T15:02:11.482Z","expires":600,"extraHeaders":{}}

You see one routr.endpoint.registered message per softphone. Softphones re-register periodically, so more arrive over time.

Make a call

From 1001, call 1002. When Routr forwards the INVITE, EdgePort publishes routr.call.started.

[#3] Received on "routr.call.started"
{"callId":"_Ax7XxHju-o7fbemWxxLww..","from":"sip:1001@sip.local","to":"sip:1002@sip.local","startTime":"2026-10-21T15:03:10.111Z","extraHeaders":{}}

Hang up. EdgePort publishes routr.call.ended with the same callId.

[#4] Received on "routr.call.ended"
{"callId":"_Ax7XxHju-o7fbemWxxLww..","endTime":"2026-10-21T15:03:55.760Z","hangupCause":"NORMAL_CLEARING","extraHeaders":{}}

Terminal running nats sub routr.call.started and receiving a JSON event with callId, from, to, and startTime — routr.call.started as shown by nats sub (captured on an earlier release, so the fields differ slightly)

Terminal running nats sub routr.call.ended and receiving a JSON event with callId, endTime, and hangupCause NORMAL_CLEARING — routr.call.ended as shown by nats sub (captured on an earlier release)

For one call you see one routr.call.started and one routr.call.ended, and both carry the same callId.

Event reference

Subject	Published when	Fields
`routr.endpoint.registered`	A REGISTER succeeds	`aor`, `registeredAt`, `expires`, `extraHeaders`
`routr.call.started`	EdgePort forwards an INVITE	`callId`, `from`, `to`, `startTime`, `extraHeaders`, plus any metadata the processor attached to the route
`routr.call.ended`	A BYE or CANCEL completes, an INVITE fails with a status above 300, or a transport error drops the transaction	`callId`, `endTime`, `hangupCause`, `extraHeaders`

extraHeaders holds every header in the message whose name starts with X-. For a list of hangup causes, see HangupCauses.java. To change the prefix, set NATS_PUBLISHER_SUBJECT. For example, NATS_PUBLISHER_SUBJECT=myserver publishes myserver.call.started, myserver.call.ended, and myserver.endpoint.registered.

To print events to EdgePort’s log instead of NATS while you debug, set CONSOLE_PUBLISHER_ENABLED=true.

Clean up

Stop and remove the containers, and delete the CLI context.

docker compose down
nats context rm local

Next steps

EdgePort

EdgePort configuration and environment variables.

Environment variables

Every variable Routr reads, by component.

SIP headers

The X- headers Routr adds and reads.

Deploy with Docker

Run Routr with Docker in production.

Get started

Concepts

How-to guides

Tutorials

Community

Stream call events to NATS

What you’ll build

Prerequisites

Steps

Event reference

Clean up

Next steps

EdgePort

Environment variables

SIP headers

Deploy with Docker

​What you’ll build

​Prerequisites

​Steps

​Event reference

​Clean up

​Next steps

EdgePort

Environment variables

SIP headers

Deploy with Docker

What you’ll build

Prerequisites

Steps

Event reference

Clean up

Next steps