CNAM Subscribe/Notify

Bandwidth’s Caller Name (CNAM) is a service that provides the Caller Name on VoIP calls in the U.S. and Canada, and can also be accessed via SIP messaging. This service adds the optional ability to query the CNAM database using the SIP SUBSCRIBE - NOTIFY framework, which is particularly useful for customers that may have already implemented this method.

Once the request is made via a SIP SUBSCRIBE message, the calling name is returned to the customer application or dial plan via a SIP NOTIFY message. The CNAM data is managed by the phone company who provides the phone numbers to its customers.

SBC (Session Border Controller) IP information

Bandwidth employs mated pairs of SBCs for signaling redundancy. For CNAM services, please ensure that both IP addresses provided are configured for inbound traffic in the event that one SBC is offline. 

To obtain the specific IPs used for the CNAM Subscribe Service, please reach out to your Implementation Specialist, if you're currently working with one. If not, please open a support ticket. 

SIP Subscribe - Notify overview

SUBSCRIBE - NOTIFY consists of 2 SIP transactions. The requestor sends a SUBSCRIBE request to initiate a CNAM DIP and Bandwidth responds with a message indicating the status of the request to complete the initial transaction. Bandwidth then sends a NOTIFY message in the opposite direction with the CNAM information and the customer responds with a message to indicate acceptance of the message containing the CNAM information. Here's what the signaling flow looks like:

Note: There's a possibility in some cases that the NOTIFY message is received before the 200 OK response to the initial SUBSCRIBE. This is as described in RFC 3265 Session Initiation Protocol (SIP)-Specific Event Notification.

Subscribe message format

The following is an example of a SIP SUBSCRIBE message requesting the CNAM information for +15551111212. The Expires header is always required and is required to be 0. The Event: cnam field identifies this message as a CNAM request. The request-id: parameter can be used by the requestor to insert an alphanumeric identifier as a reference to the request. The message body consists of only of the Calling-Party field which must contain a valid SIP URI for the number to be dipped for CNAM.

SUBSCRIBE sip:Bandwidth SIP/2.0
Via: SIP/2.0/UDP Customer;branch=ehnansucdjdisao
To: <sip:Bandwidth>
From:<sip:Customer> ;tag=1234
Call-ID: jklsfaj3kjaajl3ijrtalk3ja5352
CSeq: 150 SUBSCRIBE
Max-Forwards: 3
Contact: <sip:Customer>
Expires: 0
Event: cnam;request-id:129j2jd9
Content-Type: application/calling-name-info
Content-Length: 55
Calling-Party:sip:+15551112222@customer.com;user=phone 

Notify message format

Once the lookup is accepted and completed by Bandwidth a NOTIFY message will be sent with the CNAM info retrieved. Following is an example of a NOTIFY message in response to the SUBSCRIBE message in the previous section. The CNAM information in this case is “John’s Pizza.”

Note: the request-id information is returned in the NOTIFY message so the customer can correlate this message to the original SUBSCRIBE.

NOTIFY sip:Customer SIP/2.0
Via: SIP/2.0/UDP Bandwidth;branch=a1hB4bGnashds4
Max-Forwards: 3
Contact: <sip:Bandwidth>
To:<sip:Customer> ;tag=1234
From: <sip:Bandwidth>;tag=5678
Call-ID: jklsfaj3kjaajl3ijrtalk3ja5352
Cseq: 200 NOTIFY
Content-Type: application/calling-name-info
Subscription-State: terminated
Event: cnam;request-id:129j2jd9
Content-Length:128
Calling-Name-Status:Available
Calling-Name: “John’s Pizza”
Presentation-Indicator: allowed

Notify message format

Here are the possible error codes you may receive in response to the SUBSCRIBE message:

• 400, 500: Customer IP address not in the Access Control List
• 500: CNAM service temporarily unavailable