STIR/SHAKEN

Introduction

Spam and robocalls have become an increasingly significant problem in the US, leading to consumers losing trust in businesses. STIR/SHAKEN is a set of protocols designed for businesses to gain back this trust by authenticating the businesses making calls and the caller ID used in them.

STIR/SHAKEN stands for the Secure Telephone Identity Revisited (STIR) and Signature-based Handling of Asserted Information Using toKENs (SHAKEN). Under STIR/SHAKEN, every voice call in the US is assigned an attestation — a stamp of legitimacy provided by the originating service provider, authenticating that the call originated from its network. Calls are then passed to the terminating service provider for verification. There are three levels of call attestations:

  • Full attestation (A) — The service provider has authenticated its relationship with the customer making the call and the customer is authorized to use the calling number.
  • Partial attestation (B) — The service provider has authenticated its relationship with the customer making the call, but cannot verify that the customer is authorized to use the calling number.
  • Gateway attestation (C) — The service provider has authenticated that it has placed the call on its network, but has no relationship with the originator of the call (for example, a call received from an international gateway).

Plivo STIR verification

For both outbound and inbound Voice API calls, Plivo will display the verification status of a call as a parameter called STIR Verification, which can have one of three values:

  • Verified means the call is from a Verified caller who has authorized access to the customer’s caller ID, and hence should be treated with confidence. Verified is equivalent to attestation level A.
  • Not Verified means that, for this call, either the caller is not Verified, or it’s uncertain whether they have access to the caller ID used, or both. Not Verified means the call received attestation level B or C.
  • Not Applicable means STIR/SHAKEN doesn’t apply to this call, as would be the case if a call is not addressed to a US number or if it’s a cloud call (WebRTC or SIP).

The STIR Verification parameter will be added to:

  • Call detail records for all inbound and outbound calls.
  • As part of the information sent to answer_url, fallback_url, and hangup_url webhooks.

For outbound calls

Plivo will sign outbound calls as Verified (attestation A) for calls that use a Plivo DID as caller ID. The DID used should be rented by the same Plivo account that originates the outbound calls. All other outbound calls, assuming they are signed at all, are signed Not Verified (attestation B or C).

Note: We strongly encourage customers to use Plivo DIDs as caller ID to improve their STIR/SHAKEN verification levels.

As the regulatory ecosystem evolves, some of the rules governing the attestation level of an outbound call might be subject to change. For now, Plivo will be signing all outbound calls to the USA unless a customer violates the rules:

  1. The calls breach the Plivo Fair Usage Policy.
  2. The calls are identified as unsolicited robocalls.
  3. Plivo gets a traceback request from the Industry Traceback Group about calls made by the customer.
  4. The calls have invalid caller IDs — for instance, if they don’t adhere to E.164 format or have too many digits.

In these scenarios, Plivo may stop signing all calls initiated by the customer. That could lead to lower answer rates, because calls won’t be marked as Verified. Worst case, they could be marked as spam by receiving networks.

Note: For outbound calls to North American toll-free numbers outside the USA, users might see Verified or Not Verified values when in fact these calls are not being signed and the value should be “Not Applicable.” This is because there are shared toll-free numbers, leading to possibility of mismatch.

Plivo Console logs

In the SIP response, Plivo will send in a new header called X-Plivo-Stir-Verification whose value is one of the aforementioned three states. You can also see STIR verification values on the Voice > Logs page of the console as part of CDR.

For inbound calls

Plivo will validate attestation of calls to Plivo DIDs and toll-free numbers in the US. The validated STIR/SHAKEN verification level will be passed as part of webhook requests to various URLs — answer_url, fallback_url, and hangup_url. Verification levels will also be visible on the Plivo console and in call detail records.

Plivo Console Logs

As mentioned earlier, In the SIP response, Plivo will send in a new header called X-Plivo-Stir-Verification whose value is one of the aforementioned three states. You can also see STIR verification values on the Voice > Logs page of the console as part of CDR.