gRPC APIs Reference

Table of Contents

Top

wgtwo/annotations/annotations.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/annotations/annotations.proto

ReleaseStatus

Name Number Description
UNSPECIFIED 0
STABLE 1
BETA 2
DEPRECATED 3

File-level Extensions

Extension Type Base Number Description
scope string .google.protobuf.MethodOptions 50013
status ReleaseStatus .google.protobuf.MethodOptions 50015

Top

wgtwo/common/v0/phonenumber.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/common/v0/phonenumber.proto

NationalPhoneNumber

Any phone number that is tied to a specific country. Does not contain the prefix '+' nor a country code.

Field Type Label Description
national_phone_number string The value as a string.

PhoneNumber

A phone number that is tied to a specific country.

Field Type Label Description
e164 string Phone number formatted as E.164 with leading plus sign.

This contains of three components:

- The plus prefix
- Country code, max 3 digits
- Subscriber number

Test your number at https://libphonenumber.appspot.com/

Example: +12024561111

TextAddress

An address that is non-numerical, e.g. "MyProduct".

Field Type Label Description
text_address string The value as a string.

Top

wgtwo/callforward/v0/callforward.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/callforward/v0/callforward.proto

CallForwardingService

Method Name Request Type Response Type Description
Disable DisableCallForwardingRequest CallForwardingResponse
SetToNumber NumberCallForwardingRequest CallForwardingResponse
SetToTrunk TrunkCallForwardingRequest CallForwardingResponse
SetToVoicemail VoicemailCallForwardingRequest CallForwardingResponse

CallForwardingResponse

Field Type Label Description
status CallForwardingResponse.Status
error_message string

Conditional

Field Type Label Description
busy wgtwo.common.v0.PhoneNumber
no_reply wgtwo.common.v0.PhoneNumber
unavailable wgtwo.common.v0.PhoneNumber

ConditionalTrunkForwarding

Field Type Label Description
busy Trunk
no_reply Trunk
unavailable Trunk

DisableCallForwardingRequest

Field Type Label Description
subscriber wgtwo.common.v0.PhoneNumber

NumberCallForwardingRequest

Field Type Label Description
subscriber wgtwo.common.v0.PhoneNumber
oneof type.unconditional Unconditional
oneof type.conditional Conditional

Trunk

Field Type Label Description
id string

TrunkCallForwardingRequest

Field Type Label Description
subscriber wgtwo.common.v0.PhoneNumber
oneof type.unconditional_trunk_forwarding UnconditionalTrunkForwarding
oneof type.conditional_trunk_forwarding ConditionalTrunkForwarding

Unconditional

Field Type Label Description
forward_to_number wgtwo.common.v0.PhoneNumber

UnconditionalTrunkForwarding

Field Type Label Description
forward_to_trunk Trunk

VoicemailCallForwardingRequest

Field Type Label Description
subscriber wgtwo.common.v0.PhoneNumber
oneof target.default google.protobuf.Empty
oneof target.phone_number wgtwo.common.v0.PhoneNumber

CallForwardingResponse.Status

Name Number Description
UNKNOWN 0
ACCEPTED 1
REJECTED 2

Top

wgtwo/common/v0/errors.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/common/v0/errors.proto

StatusCode

Shared status codes

Name Number Description
STATUS_CODE_UNSPECIFIED 0 Unspecified/default status code; do not use.
STATUS_CODE_OK 1 Success.
STATUS_CODE_NOT_ACCEPTABLE 2 The request is not acceptable.
STATUS_CODE_ACCESS_DENIED 3 Access denied. The request is not authorized; the access token may not have the necessary scopes or targeting the wrong resource.
STATUS_CODE_INTERNAL_ERROR 4 Internal error. The request could not be processed due to an error on the server side.

Top

wgtwo/common/v0/types.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/common/v0/types.proto

Fqdn

Fully Qualified Domain Name

Field Type Label Description
value string The value as a string.

GlobalTitle

A global title is an address used in the SCCP protocol for routing signaling messages on telecommunications networks.

Field Type Label Description
value string The value as a string.

Iccid

The Integrated Circuit Card Identification number (ICCID) is an 18-22-digit number typically printed on the back of a SIM card

Field Type Label Description
value string The value as a string.

Imsi

International Mobile Subscription Identity An IMSI is composed of three parts:

  1. Mobile Country Code (MCC) consisting of three digits.

The MCC is 3 digits long and identifies uniquely the country of domicile of the mobile subscription

  1. Mobile Network Code (MNC), 2 or 3 digits for 3GPP network applications.

    The MNC in combination with the MCC identify the home PLMN of the mobile subscription. The length of the MNC in most cases depends on the value of the MCC. Note that some MCC use a mixture of two and three digit MNC codes.

  2. Mobile Subscriber Identification Number (MSIN) identifying the mobile subscription within a PLMN.

Normally there are 10 digits, but can be fewer in the case of a 3-digit MNC or if national regulations indicate that the total length of the IMSI should be less than 15 digits.

Field Type Label Description
value string The value as a string.

NetworkIdentity

Home network identity; composed of a Mobile Country Code (MCC) and a Mobile Network Code (MNC).

Field Type Label Description
mcc string Mobile Country Code, e.g. "262" for Germany.
mnc string Mobile Network Code, e.g. "01" for T-Mobile Germany, when mcc is "262".

SubscriptionIdentifier

Subscription identifier message.

Field Type Label Description
value string A globally unique string identifying a subscription. This will stay the same even if msisdn of subscription changes
tenant Tenant The tenant (operator) of the subscription.

Tadig

TADIG code is a number uniquely identifying network operators in a GSM mobile network. The acronym TADIG expands to "Transferred Account Data Interchange Group".

Field Type Label Description
value string The value as a string.

Tenant

The tenant (operator) message.

Field Type Label Description
name string The name of the tenant (operator) on the platform.

NetworkGeneration

Enum for network generations is a type of cellular network generally referred to by its number. E.g.: 2G, 3G, 4G, 5G.

Name Number Description
NETWORK_GENERATION_UNSPECIFIED 0 Unspecified network generation; default value. Do not use.
NETWORK_GENERATION_2G 1 2G
NETWORK_GENERATION_3G 2 3G
NETWORK_GENERATION_4G 3 4G
NETWORK_GENERATION_5G 4 5G

Top

wgtwo/common/v1/phonenumber.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/common/v1/phonenumber.proto

Alphanumeric

An alphanumeric address. This is usually just be the name of a product or service. Alphanumeric addresses are usually not routable, and can thus only be used in origin addresses.

Field Type Label Description
text string The value as a string, e.g.: "MyService"

E164

An international phone number formatted as E.164 with leading plus sign

This contains three components:

  • The plus prefix
  • Country code, 1 to 3 digits
  • Subscriber number

Example "+4787654321" as '+' '47' '87654321'.

The number may contain sequences that do not strictly conform to the E.164 number standard (e.g. too long), but shall always follow the three components as described above.

Field Type Label Description
e164 string The value as a string, e.g.: "+4787654321"

National

A national number can be anything that is usually typed into a number field for phone numbers, SMS etc. It shall only contains digits (0-9), and the meaning of the number sequence is dependent on the country of the relevant operator.

Field Type Label Description
number string The value as a string, e.g.: "87654321"

Top

wgtwo/common/v1/types.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/common/v1/types.proto

Country

Country information

All programmatic use should depend on the alpha-2 code, and NOT the human readable name

Field Type Label Description
code string ISO 3166-1 alpha-2 code. Examples: US, NO, SE
name string Human readable name

ImeiSv

International Mobile station Equipment Identity and Software Version number An IMEI is composed of four parts:

  1. an 8 digit Type Allocation Code (TAC);
  2. a 6 digit Serial Number (SNR);
  3. an optional Check Digit (CD); and
  4. an optional 2 digit Software Version Number (handled separately). For more information see ETSI 123.003 Chapter 6 and Appendix B.
Field Type Label Description
imei string The imei as a string.
software_version string The software version as a string.

Imsi

International Mobile Subscription Identity An IMSI is composed of three parts:

  1. Mobile Country Code (MCC) consisting of three digits. The MCC is 3 digits long and identifies uniquely the country of domicile of the mobile subscription;
  2. Mobile Network Code (MNC), 2 or 3 digits for 3GPP network applications. The MNC identifies the home PLMN of the mobile subscription. The length of the MNC depends on the value of the MCC. A mixture of two and three digit MNC codes within a single MCC area is not recommended.
  3. Mobile Subscriber Identification Number (MSIN) identifying the mobile subscription within a PLMN. Normally there are 10 digits, but can be fewer in the case of a 3-digit MNC or if national regulations indicate that the total length of the IMSI should be less than 15 digits.
Field Type Label Description
value string The value of the imsi as a string.

IpAddressV4

IpAddress v4

Field Type Label Description
value string The ip address as a string.

NetworkIdentity

Home network identity; composed of a Mobile Country Code (MCC) and a Mobile Network Code (MNC).

Field Type Label Description
mcc string Mobile Country Code, e.g. "262" for Germany.
mnc string Mobile Network Code, e.g. "01" for T-Mobile Germany, when mcc is "262".

SubscriptionIdentifier

Subscription Identification: The wg2rn field follows the format {tenant}:{region}:{id}, where:

  • tenant: The tenant to which this subscription belongs
  • region: The region code of the subscription's MSISDN
  • id: A static identifier for the subscription

The wg2rn uniquely identifies a subscription.

Note: Our OAuth 2.0 server supports Pairwise Pseudonymous Identifiers for the 'sub' field. All clients of a product share the same identifier for a single subscription, stored in the 'value' field. Please be aware that the 'value' field is deprecated and will be removed in the future.

Field Type Label Description
value string Deprecated.
wg2rn string The value of the Subscription identifier as a string

Top

wgtwo/consents/v0/consents.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/consents/v0/consents.proto

ConsentService

ConsentService is a service for managing consents for a subscription.

Method Name Request Type Response Type Description
GetConsentsForSubscription GetConsentsForSubscriptionRequest GetConsentsForSubscriptionResponse Returns the consents for a subscription.
CreateConsentForSubscription CreateConsentForSubscriptionRequest CreateConsentForSubscriptionResponse Create a consent for a subscription.
RevokeConsentForSubscription RevokeConsentForSubscriptionRequest RevokeConsentForSubscriptionResponse Revoke a consent for a subscription.

A consent for a subscription.

Field Type Label Description
owner ConsentOwner The owner of the consent.
product_id string The product identifier.
scopes Scope repeated The scopes of the consent.
revokable bool Whether the consent is revocable.
metadata Consent.MetadataEntry repeated

Consent.MetadataEntry

Field Type Label Description
key string
value string

ConsentOwner

The owner of a consent.

Field Type Label Description
oneof value.subscription Subscription The subscription owns the consent.
oneof value.tenant wgtwo.common.v0.Tenant The tenant (operator) owns the consent, on behalf of the subscription.

CreateConsentForSubscriptionRequest

Request to create a consent for a subscription.

Field Type Label Description
id wgtwo.common.v0.SubscriptionIdentifier The subscription identifier.
phone_number wgtwo.common.v0.PhoneNumber The phone number of the subscriber. Planned for removal. Please use id above.
product_id string The product identifier.
metadata CreateConsentForSubscriptionRequest.MetadataEntry repeated

CreateConsentForSubscriptionRequest.MetadataEntry

Field Type Label Description
key string
value string

CreateConsentForSubscriptionResponse

Create a consent for a subscription response.

Field Type Label Description
status_code wgtwo.common.v0.StatusCode The status code of the response.
error_message string The error message of the response. Empty for successes.

GetConsentsForSubscriptionRequest

Request to get consents for a subscription.

Field Type Label Description
id wgtwo.common.v0.SubscriptionIdentifier The subscription identifier.
phone_number wgtwo.common.v0.PhoneNumber The phone number of the subscriber. Planned for removal. Please use id above.

GetConsentsForSubscriptionResponse

Response to get consents for a subscription.

Field Type Label Description
consents Consent repeated The consents for the subscription.
status_code wgtwo.common.v0.StatusCode The status code of the response.
error_message string The error message of the response. Empty for successes.

RevokeConsentForSubscriptionRequest

Request to revoke a consent for a subscription.

Field Type Label Description
id wgtwo.common.v0.SubscriptionIdentifier The subscription identifier.
phone_number wgtwo.common.v0.PhoneNumber The phone number of the subscriber. Planned for removal. Please use id above.
product_id string The product identifier.

RevokeConsentForSubscriptionResponse

Revoke a consent for a subscription response.

Field Type Label Description
status_code wgtwo.common.v0.StatusCode The status code of the response.
error_message string The error message of the response. Empty for successes.

Scope

The scope of a consent.

Field Type Label Description
property string The name of the scope, e.g. "subscription.consent:read".

Subscription

A subscription message.

Field Type Label Description
subscription_identifier wgtwo.common.v0.SubscriptionIdentifier The subscription identifier.

Top

wgtwo/events/v1/events.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/events/v1/events.proto

AckInfo

This contains a opaque string which must be included in the ack request to identify the event

Field Type Label Description
value string Opaque string that must be included in the ack request to identify the event

AckRequest

Ack request, which is required for sending a ack of an event

Field Type Label Description
ack_info AckInfo Information that must be included in the ack request to identify the event

AckResponse

This response includes the status of the ack request

Field Type Label Description
ack_status AckStatus If the ack request was successful or not

AckStatus

Status of the ack request

If status is not successful, the ack request may be retried. Everything except AckStatusCodeACK_STATUS_SUCCESS should be treated as a failure

Field Type Label Description
status_code AckStatus.StatusCode Status of the ack request

DurableQueue

All connected clients with the same name will share the stream, so that an event will only be seen be a single client.

The server will store the clients reading position for 1 hour after the client has disconnected. That would make it possible for a client to resume reading after it has been disconnected.

If e.g. five group of clients should see all events in the stream, each group must be given a unique name.

Field Type Label Description
custom_name string Optional: Messages will by default be shared between all connections using the same OAuth 2.0 client

Identifier

Identity of the subscription this event was generated for.

Field Type Label Description
subscription_identifier wgtwo.common.v1.SubscriptionIdentifier The subscription identifier

Metadata

Metadata about the event

Field Type Label Description
timestamp google.protobuf.Timestamp The timestamp this event was generated
identifier Identifier Identity of the subscription this event was generated for.
ack_info AckInfo Information that must be included in the ack request to identify the event
is_redelivered bool True when this is not the first time the message has been sent

RegularStream

All connected clients will see all events in the stream. Reading position is not stored at the server, so disconnecting will make it start fresh.

StreamConfiguration

This is the configuration for setting up a event stream from our APIs.

The client will be forced to reconnect after one hour to ensure it is using fresh access tokens.

The default settings should be well suited for production usage, but 'max_in_flight' may be tweaked.

Regular: Warning: This is intended for testing purposes only and is not recommended for production.

All connected clients will see all events in the stream. Reading position is not stored at the server, so disconnecting will make it start fresh.

Durable Queue: All connected clients with the same name will share the stream, so that an event will only be seen be a single client.

The server will store the clients reading position for 1 hour after the client has disconnected. That would make it possible for a client to resume reading after it has been disconnected.

Note: - The custom_name is namespaced to be per OAuth 2.0 client, so using the same name for two different OAuth 2.0 clients will not make them part of the same stream.

Example: Giving the following configuration, you may get approximately the distribution shown below: 3 × custom_name = "" (default) 2 × custom_name = "alice" 1 × custom_name = "bob"

       ┌─►33 % ─► ""
 ─ ─ ──┼─►33 % ─► ""
       └─►33 % ─► ""
 ─ ─ ──┬─►50 % ─► "alice"
       └─►50 % ─► "alice"
 ─ ─ ────►100 ──► "bob"

Acknowledge: The server will for the client to sent a ack message. If no such message has been received within 30 seconds, the event will be resent.

Max in-flight: The server will only allow, by default, 50 in-flight unacknowledged events. In combination with requiring acks, this allows the client to apply some backpressure.

Note that max in-flight > 1 may cause events to be received out-of-order, something the client must design for.

Start Position: This decides the policy used when a client connects without having its reading position stored at the server. The start position may be set to

  • only include new events (events created after connection)
  • a specific ID
  • starting at a given time
  • deliver all available events

All settings are optional, with the following set as default:

  • Events are load balanced between all connected clients using the same OAuth 2.0 client

  • Current reading position is remembered on the server for 1 hour, even if no clients are connected That is, reading may resume even if the clients needs to disconnect

  • The clients needs to send a ack after processing a event If a client does not ack within 30 seconds, the event will be resent

  • 50 un-acknowledged events will be allowed at once

  • If reading position is not stored in server, that is on first connection or if all clients has been gone for 30 minutes, only new events will be included.

Field Type Label Description
oneof stream_type.regular RegularStream Receives messages only while connected; misses messages published when disconnected.
oneof stream_type.durable_queue DurableQueue Remembers message position, resumes receiving messages after disconnection within a permissible time frame.
oneof acknowledge_option.disable_explicit_ack google.protobuf.Empty Disable ack
oneof acknowledge_option.custom_ack_timeout google.protobuf.Duration Must be between 10 seconds and 10 minutes
max_in_flight uint32 Optional: By default, max 50 unacknowledged events may be in-flight Must be between 1 and 200
oneof start_position.start_at_new google.protobuf.Empty Will only deliver events generated after this subscription was started
oneof start_position.start_at_id uint64 Will deliver events from the given ID
oneof start_position.start_at_timestamp google.protobuf.Timestamp Will deliver events from the given timestamp
oneof start_position.start_at_oldest_possible google.protobuf.Empty Will deliver all available events

AckStatus.StatusCode

Status of the ack request enum

Name Number Description
STATUS_CODE_UNSPECIFIED 0 Unspecified status code; it's a server error if this is returned
STATUS_CODE_FAILURE 1 The ack request failed
STATUS_CODE_SUCCESS 2 The ack request was successful

Top

wgtwo/consents/v1/consent_events.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/consents/v1/consent_events.proto

ConsentEventService

Consent events are events triggered by granting, updating or revoking consents for your product, either for a single user or for an operator. The events can originate from:

  • Bundling of your product for a subscriber
  • Preview consent added by Cisco on your behalf
  • Operator consent covering all subscribers for an operator
  • Subscriber signing up to your product
Method Name Request Type Response Type Description
StreamConsentChangeEvents StreamConsentChangeEventsRequest StreamConsentChangeEventsResponse stream Stream consent change events.
AckConsentChangeEvent AckConsentChangeEventRequest AckConsentChangeEventResponse Acknowledge a consent change event.

AckConsentChangeEventRequest

Request message for acknowledging a consent change event.

Field Type Label Description
ack_info wgtwo.events.v1.AckInfo Used to identify the event to acknowledge.

AckConsentChangeEventResponse

Response message for acknowledging a consent change event.

Field Type Label Description
ack_status wgtwo.events.v1.AckStatus The status response (success/failure) of the acknowledgement.

ConsentAdded

The consent added event message.

Field Type Label Description
scopes string repeated The scopes for the consent.

ConsentChangeEvent

The consent change event message.

Field Type Label Description
oneof type.added ConsentAdded A consent was added.
oneof type.updated ConsentUpdated A consent was updated.
oneof type.revoked ConsentRevoked A consent was revoked.
oneof target.number wgtwo.common.v1.E164 The international number of the subscriber.
oneof target.tenant string The operator (tenant) on the platform.

ConsentRevoked

The consent revoked event message.

ConsentUpdated

The consent updated event message.

Field Type Label Description
scopes string repeated The updated scopes for the consent.

StreamConsentChangeEventsRequest

Request message for streaming consent change events.

Field Type Label Description
stream_configuration wgtwo.events.v1.StreamConfiguration The stream configuration.

StreamConsentChangeEventsResponse

Response message for streaming consent change events.

Field Type Label Description
metadata wgtwo.events.v1.Metadata Metadata for the stream.
consent_change_event ConsentChangeEvent The consent change event.

Top

wgtwo/events/v0/events.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/events/v0/events.proto

EventsService

Method Name Request Type Response Type Description
Subscribe SubscribeEventsRequest SubscribeEventsResponse stream
Ack AckRequest AckResponse

AckRequest

Field Type Label Description
inbox string
sequence uint64

AckResponse

ConsentRevokeEvent

Field Type Label Description
msisdn wgtwo.common.v0.PhoneNumber

CountryChangeEvent

Field Type Label Description
msisdn wgtwo.common.v0.PhoneNumber
previous CountryChangeEvent.Country
current CountryChangeEvent.Country

CountryChangeEvent.Country

Field Type Label Description
code string
name string

Event

Field Type Label Description
metadata EventMetadata
timestamp google.protobuf.Timestamp
service_id string
oneof event.voice_event VoiceEvent
oneof event.voicemail_event VoicemailEvent
oneof event.location_update_event LocationUpdateEvent
oneof event.country_change_event CountryChangeEvent
oneof event.token_audit_event TokenAuditEvent
oneof event.sms_event SmsEvent
oneof event.sms_delivery_report_event SmsDeliveryReportEvent
oneof event.consent_revoke_event ConsentRevokeEvent
oneof event.handset_update_event HandsetUpdateEvent
oneof event.first_attachment_event FirstAttachmentEvent
oneof event.periodic_country_event PeriodicCountryEvent
owner Owner

EventMetadata

Field Type Label Description
sequence uint64
is_redelivered bool
ack_inbox string

FirstAttachmentEvent

Field Type Label Description
number wgtwo.common.v0.PhoneNumber
imsi Imsi

Handset

Field Type Label Description
imei_sv ImeiSv

HandsetUpdateEvent

Field Type Label Description
previous Handset
current Handset
imsi Imsi
number wgtwo.common.v0.PhoneNumber

ImeiSv

Field Type Label Description
imei string
software_version string

Imsi

Field Type Label Description
value string

LocationUpdateEvent

Field Type Label Description
number wgtwo.common.v0.PhoneNumber
previous LocationUpdateEvent.Locations
current LocationUpdateEvent.Locations

LocationUpdateEvent.Fqdn

Fully Qualified Domain Name The format commonly used for representing an MME address

Field Type Label Description
value string

LocationUpdateEvent.GlobalTitle

(see section 5 in Numbering, Addressing and Identification) A GT is a phone number formatted according to E.164 that is used to identify MSCs, VLRs, HLRs, SGSNs and other nodes for routing purposes.

Field Type Label Description
value string

LocationUpdateEvent.Locations

Field Type Label Description
msc LocationUpdateEvent.GlobalTitle
vlr LocationUpdateEvent.GlobalTitle
sgsn LocationUpdateEvent.GlobalTitle
mme LocationUpdateEvent.Fqdn

ManualAckConfig

Field Type Label Description
enable bool
timeout google.protobuf.Duration

Owner

Field Type Label Description
phone_number wgtwo.common.v0.PhoneNumber
sub string

PeriodicCountryEvent

Field Type Label Description
number wgtwo.common.v0.PhoneNumber
imsi Imsi
country CountryChangeEvent.Country

SmsDeliveryReportEvent

Field Type Label Description
id string
oneof from_address.from_e164 wgtwo.common.v0.PhoneNumber
oneof from_address.from_national_phone_number wgtwo.common.v0.NationalPhoneNumber
oneof from_address.from_text_address wgtwo.common.v0.TextAddress
oneof to_address.to_e164 wgtwo.common.v0.PhoneNumber
oneof to_address.to_national_phone_number wgtwo.common.v0.NationalPhoneNumber
oneof to_address.to_text_address wgtwo.common.v0.TextAddress
direction SmsDeliveryReportEvent.Direction
sms_id string
status SmsDeliveryReportEvent.Status

SmsEvent

Field Type Label Description
id string Identifier referring to a unique instance of this message during its routing. If the message is delivered multiple times to the same receiver, this ID will be different. See uuid that is constant across all routes.
oneof from_address.from_e164 wgtwo.common.v0.PhoneNumber
oneof from_address.from_national_phone_number wgtwo.common.v0.NationalPhoneNumber
oneof from_address.from_text_address wgtwo.common.v0.TextAddress
oneof to_address.to_e164 wgtwo.common.v0.PhoneNumber
oneof to_address.to_national_phone_number wgtwo.common.v0.NationalPhoneNumber
oneof to_address.to_text_address wgtwo.common.v0.TextAddress
direction SmsEvent.Direction
oneof content.text string
oneof content.bytes bytes
uuid string Unique identifier of a message. If the message is delivered multiple times to the same receiver, this uuid will remain the same.

SubscribeEventsRequest

Field Type Label Description
type EventType repeated
oneof start_position.start_at_sequence uint64
oneof start_position.start_at_timestamp google.protobuf.Timestamp
oneof start_position.start_at_time_delta google.protobuf.Duration
oneof start_position.start_with_last_received google.protobuf.Empty
oneof start_position.start_at_oldest_possible google.protobuf.Empty
client_id string
queue_name string
durable_name string
max_in_flight uint32
manual_ack ManualAckConfig

SubscribeEventsResponse

Field Type Label Description
event Event

TokenAuditEvent

Field Type Label Description
operation TokenAuditEvent.Operation
oneof token_changed.operator_token TokenAuditEvent.OperatorTokenChanged

TokenAuditEvent.OperatorTokenChanged

Field Type Label Description
new TokenAuditEvent.OperatorTokenMetadata
old TokenAuditEvent.OperatorTokenMetadata

TokenAuditEvent.OperatorTokenMetadata

Field Type Label Description
client_id string
name string
rights string repeated

VoiceEvent

Field Type Label Description
call_id string
type VoiceEvent.VoiceEventType
from_number wgtwo.common.v0.PhoneNumber
to_number wgtwo.common.v0.PhoneNumber
caller_id_hidden bool

VoicemailEvent

Field Type Label Description
voicemail_id string
type VoicemailEvent.VoicemailEventType
from_number wgtwo.common.v0.PhoneNumber
to_number wgtwo.common.v0.PhoneNumber

EventType

Name Number Description
UNSPECIFIED 0
VOICE_EVENT 1
VOICEMAIL_EVENT 2
LOCATION_UPDATE_EVENT 3
COUNTRY_CHANGE_EVENT 4
TOKEN_AUDIT_EVENT 5
SMS_EVENT 6
SMS_DELIVERY_REPORT_EVENT 7
CONSENT_REVOKE_EVENT 8
HANDSET_UPDATE_EVENT 9
FIRST_ATTACHMENT_EVENT 10
PERIODIC_COUNTRY_EVENT 11

SmsDeliveryReportEvent.Direction

Name Number Description
DIRECTION_UNKNOWN 0
FROM_SUBSCRIBER 1
TO_SUBSCRIBER 2

SmsDeliveryReportEvent.Status

Name Number Description
STATUS_UNKNOWN 0
DELIVERED 1
TEMPORARY_FAILURE 2
FINAL_FAILURE 3
EXPIRED 4

SmsEvent.Direction

Name Number Description
UNKNOWN 0
FROM_SUBSCRIBER 1
TO_SUBSCRIBER 2

TokenAuditEvent.Operation

Name Number Description
UNDEFINED 0
CREATED 1
MODIFIED 2
DELETED 3

VoiceEvent.VoiceEventType

Name Number Description
UNSPECIFIED 0
CALL_INITIATED 1
CALL_RINGING 2
CALL_ANSWERED 3
CALL_ENDED 4
CALL_FWD_VOICEMAIL 5

VoicemailEvent.VoicemailEventType

Name Number Description
UNSPECIFIED 0
NEW_VOICEMAIL 1

Top

wgtwo/images/v0/images.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/images/v0/images.proto

Image

Image is a message that represents an image.

Field Type Label Description
url string Image URL The URL might change and should not be stored by the client. Example: "https://example.com/image.png"

Top

wgtwo/lookup/v0/number_lookup.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/lookup/v0/number_lookup.proto

NumberLookupService

Method Name Request Type Response Type Description
NumberLookup NumberLookupResponse stream NumberLookupRequest stream

CacheControl

Field Type Label Description
max_age google.protobuf.Duration The maximum duration for which this response can be cached.

If unset or set to zero, default duration of 24 hours will be used. If set to value lower than the minimum duration of 15 minutes, the minimum duration will be used.

Note: The minimum and default values might be subject to change without notice. |

Error

Field Type Label Description
message string Human readable description describing the error

NumberLookupRequest

Field Type Label Description
id string An ID representing the request, used for routing purposes
number wgtwo.common.v0.PhoneNumber The number to lookup

NumberLookupResponse

Field Type Label Description
number_lookup_request NumberLookupRequest The origin request this response is for
oneof reply.result Result
oneof reply.error Error
cache_control CacheControl Cache settings for this response

Result

Field Type Label Description
name string The name associated with the number May be empty if no name is found

Top

wgtwo/mms/v0/mms.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/mms/v0/mms.proto

MmsService

Method Name Request Type Response Type Description
SendMessageToSubscriber SendMessageToSubscriberRequest SendResponse
SendMessageFromSubscriber SendMessageFromSubscriberRequest SendResponse

AudioContent

Field Type Label Description
oneof content.mp3 bytes
oneof content.opus bytes
oneof content.amr bytes
oneof content.wav bytes

ImageContent

Field Type Label Description
oneof content.png bytes
oneof content.jpg bytes

MessageContent

Field Type Label Description
oneof content.audio AudioContent
oneof content.text TextContent
oneof content.image ImageContent

SendMessageFromSubscriberRequest

Field Type Label Description
message_content MessageContent repeated
from_subscriber wgtwo.common.v0.PhoneNumber
to_e164 wgtwo.common.v0.PhoneNumber

SendMessageToSubscriberRequest

Field Type Label Description
message_content MessageContent repeated
oneof from_address.from_e164 wgtwo.common.v0.PhoneNumber
oneof from_address.from_text_address wgtwo.common.v0.TextAddress
to_subscriber wgtwo.common.v0.PhoneNumber

SendResponse

Field Type Label Description
request_id string
status SendResponse.SendStatus
description string

TextContent

Field Type Label Description
text string

SendResponse.SendStatus

Name Number Description
UNKNOWN 0
SEND_OK 1
SEND_REJECT 2
SEND_ERROR 3

Top

wgtwo/number_portability/v0/number_portability.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/number_portability/v0/number_portability.proto

NumberPortabilityService

NumberPortabilityService is supposed to be used by tenants or third parties to import country-specific number porting records into Working Group Two's number portability database. A porting record consists of a subscriber number, recipient operator, porting date and optional routing code as well as tenant-specific metadata. Porting date can both be a past or a future date.

Method Name Request Type Response Type Description
CreatePortingRecords CreatePortingRecordsRequest CreatePortingRecordsResponse CreatePortingRecords is used to import porting records into the number portability database.
ListPortingRecords ListPortingRecordsRequest ListPortingRecordsResponse ListPortingRecords is used to list porting records from the number portability database.

CreatePortingRecordsRequest

Request message to create porting records.

Field Type Label Description
records PortingRecord repeated Porting records to be created.

CreatePortingRecordsResponse

Response message for create porting records.

ListPortingRecordsRequest

Request message to list porting records.

Field Type Label Description
oneof _operator_code.operator_code string optional Optional subscriber number prefix to filter porting records.
oneof _subscriber_number_prefix.subscriber_number_prefix string optional Optional operator code to filter porting records.
oneof _valid_from.valid_from google.protobuf.Timestamp optional Optional porting date to filter porting records.

ListPortingRecordsResponse

Response message for list porting records.

Field Type Label Description
records PortingRecord repeated Porting records.

PortingRecord

Message representing a porting record.

Field Type Label Description
subscriber_number wgtwo.common.v1.E164 Subscriber number with a country code.
operator_code string A new operator's code (in Sweden this is SPID allocated by SNPAC).
routing_code string Routing code of the new operator, used at least in Sweden.
valid_from google.protobuf.Timestamp Porting date and time.
metadata PortingRecord.MetadataEntry repeated May be used to store tenant-specific data.

PortingRecord.MetadataEntry

Field Type Label Description
key string
value string

Top

wgtwo/number_portability/v1/number_portability.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/number_portability/v1/number_portability.proto

NumberBlockService

In some countries, a subscriber number itself may not be sufficient to determine the routing code for non-ported numbers. For example, in Belgium, an earliest number prefix allocated to an operator must be used, separately for fixed-line and mobile numbers. NumberBlockService allows to create, update, delete and list number blocks allocated to operators by a regulator.

Method Name Request Type Response Type Description
CreateOrUpdateNumberBlock CreateOrUpdateNumberBlockRequest CreateOrUpdateNumberBlockResponse Creates a new or updates an existing number block.
DeleteNumberBlock DeleteNumberBlockRequest DeleteNumberBlockResponse Deletes an existing number block.
ListNumberBlocks ListNumberBlocksRequest ListNumberBlocksResponse List existing number blocks.

NumberPortabilityService

NumberPortabilityService is supposed to be used by tenants or third parties to import country-specific number porting records into Working Group Two's number portability database. A porting record consists of a subscriber number, routing destination, porting date and optional routing code as well as tenant-specific metadata. Porting date can both be a past or a future date.

Method Name Request Type Response Type Description
CreatePortingRecords CreatePortingRecordsRequest CreatePortingRecordsResponse CreatePortingRecords is used to import porting records into the number portability database. It may also be used to clear the porting record to return it to it's original number block - for that, destination_id, operator_code and routing_code in the PortingRecords should be set to empty values.
ListPortingRecords ListPortingRecordsRequest ListPortingRecordsResponse ListPortingRecords is used to list porting records from the number portability database.

RoutingDestinationService

RoutingDestinationService is supposed to be used by tenants or third parties to create, update, delete and list routing destinations, which define how SMS messages or called should be routed. A porting record may be associated either directly to the routing code or indirectly via routing destinations (destination_id field of the PortingRecord message). Indirect association facilitates routing code changes without updating all porting records.

Method Name Request Type Response Type Description
CreateOrUpdateDestination CreateOrUpdateDestinationRequest CreateOrUpdateDestinationResponse Creates a new or updates an existing routing destination.
DeleteDestination DeleteDestinationRequest DeleteDestinationResponse Deletes an existing routing destination.
ListDestinations ListDestinationsRequest ListDestinationsResponse List existing mobile routing destinations.

CreateOrUpdateDestinationRequest

Field Type Label Description
destination RoutingDestination

CreateOrUpdateDestinationResponse

Field Type Label Description
destination_id string

CreateOrUpdateNumberBlockRequest

Field Type Label Description
block NumberBlock

CreateOrUpdateNumberBlockResponse

Intentionally left blank.

CreatePortingRecordsRequest

Request message to create porting records.

Field Type Label Description
records PortingRecord repeated Porting records to be created.

CreatePortingRecordsResponse

Response message for create porting records.

Intentionally left blank.

DeleteDestinationRequest

Field Type Label Description
destination_id string

DeleteDestinationResponse

Intentionally left blank.

DeleteNumberBlockRequest

Field Type Label Description
destination_id string
prefix string

DeleteNumberBlockResponse

Intentionally left blank.

ListDestinationsRequest

Field Type Label Description
oneof _destination_id.destination_id string optional

ListDestinationsResponse

Field Type Label Description
destinations RoutingDestination repeated

ListNumberBlocksRequest

Field Type Label Description
oneof _destination_id.destination_id string optional
oneof _prefix.prefix string optional
oneof _status.status NumberBlockStatus optional

ListNumberBlocksResponse

Field Type Label Description
blocks NumberBlock repeated

ListPortingRecordsRequest

Request message to list porting records.

Field Type Label Description
oneof _operator_code.operator_code string optional Optional operator code to filter porting records.
oneof _subscriber_number_prefix.subscriber_number_prefix string optional Optional subscriber number prefix to filter porting records.
oneof _destination_id.destination_id string optional Optional destination ID to filter porting records.
oneof _valid_from.valid_from google.protobuf.Timestamp optional Optional minimum porting date to filter porting records.

ListPortingRecordsResponse

Response message for list porting records.

Field Type Label Description
records PortingRecord repeated Porting records.

NumberBlock

A block of subscriber numbers identified by a prefix. Non-ported numbers will be matched against the prefixes to determine the routing destination, which in turn will be used to determine the routing code.

Field Type Label Description
destination_id string A reference to the destination created in the RoutingDestinationService.
prefix string Subscriber number prefix.
status NumberBlockStatus Status of a number block. Only reserved and allocated blocks are used for the lookups.
oneof _assignment_date.assignment_date google.protobuf.Timestamp optional Only blocks with assignment date in the past are used for the lookups.

PortingRecord

Message representing a porting record (or lack thereof, in case destination_id, operator_code and routing_code are empty).

Field Type Label Description
subscriber_number wgtwo.common.v1.E164 Subscriber number with a country code.
valid_from google.protobuf.Timestamp Porting date and time.
destination_id string Destination ID to route calls or messages to. May be empty if destinations are not used.
operator_code string A free-form operator code (in Sweden this is SPID allocated by SNPAC). May be empty.
routing_code string Country-specific code used to route calls or messages If empty and destination_id is set, the effective routing code is resolved from the destination.
metadata PortingRecord.MetadataEntry repeated May be used to store tenant-specific data.

PortingRecord.MetadataEntry

Field Type Label Description
key string
value string

RoutingDestination

Routing destination defines how the messages or calls should be routed. It can correspond to an operator, a particular subset of numbers, an interconnect partner, etc. In the current implementation, it defines the routing code which is appended to the subscriber number when sending messages or making calls.

Field Type Label Description
id string Destination's unique identifier. Mandatory.
name string Informational destination name.
routing_code string Country-specific code used to route calls or messages In Belgium this is a C-code that is the earliest block assigned to an operator by the regulator.

NumberBlockStatus

Name Number Description
UNKNOWN_UNSPECIFIED 0
R_RESERVED 1 R Number Range reserved
A_ALLOCATED 2 A Allocated
F_FREE 3 F Number range Free
RC_RESERVED 4 RC Number Range reserved
T_RESERVED_UNDER_TESTING 5 T Number range reserved under testing
U_UNAVAILABLE 6 U Unavailable
B_BLOCKED 7 B Blocked (no reservation possible)

Top

wgtwo/products/v0/products.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/products/v0/products.proto

ProductService

Method Name Request Type Response Type Description
ListProductsForTenant ListProductsForTenantRequest ListProductsForTenantResponse

ListProductsForTenantRequest

Field Type Label Description
tenant string Required: Show products available for tenant

ListProductsForTenantResponse

Field Type Label Description
products Product repeated

Product

Field Type Label Description
id string
name string
subtitle string
product_url string
description string
icon wgtwo.images.v0.Image
banner wgtwo.images.v0.Image
images wgtwo.images.v0.Image repeated

Top

wgtwo/sim/v0/authentication.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/sim/v0/authentication.proto

SimAuthenticationService

Method Name Request Type Response Type Description
GenerateEapAkaAuthenticationVector GenerateEapAkaAuthenticationVectorRequest GenerateEapAkaAuthenticationVectorResponse

EapAkaAuthenticationVector

Field Type Label Description
rand bytes
xres bytes
autn bytes
ck bytes
ik bytes

GenerateEapAkaAuthenticationVectorRequest

Field Type Label Description
imsi wgtwo.common.v1.Imsi

GenerateEapAkaAuthenticationVectorResponse

Field Type Label Description
authentication_vector EapAkaAuthenticationVector

Top

wgtwo/sipbreakout/v1/sipbreakout.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/sipbreakout/v1/sipbreakout.proto

SipBreakoutService

Virtual SIP Registration makes Mobility Services' core involve a third party Telephony Application Server (TAS) in to the call processing. The Mobility Services' core Session Boarder Controller (SBC) will forward SIP signalling to the TAS based on presence of the SIP Registration and its type. The type can be one of "loop", "fork", or "fallback".

  ┌───────┐                   |    ┌───────┐
  │ Alice ├───1───────┐       |    │ Alice ├───1───────┐
  └───────┘           │       |    └───────┘           │
                      │       |                        │
  ┌──────┐         ┌──▼───┐   |    ┌───────┐        ┌──▼───┐
  │ Bob  ◄────4────┤ Core │   |    │ Bob   ◄───2────┤ Core │
  └──────┘         └─▲───┬┘   |    └───────┘        └──┬───┘
                     3   2    |                        3
                     │   │    |                        │
                    ┌┴───▼┐   |                     ┌──▼──┐
                    │ TAS │   |                     │ TAS │
                    └─────┘   |                     └─────┘
                              |
          Loop                VS       Fork / Fallback

For ROUTE_TYPE_LOOP leg 4 is not created until call comes back as leg 3. In this case, TAS is not obliged to create leg 3, and can itself answer or reject leg 2.

For ROUTE_TYPE_FORK registration makes legs 2 and 3 to happen simultaneously.

For ROUTE_TYPE_FALLBACK case leg 3 will only be created if leg 2 is not answered.

For better control of the Loop logic, 2 subtypes of LOOP route type exists:

ROUTE_TYPE_LOOP_MO: Will loop a call only if direction of the call is mobile originating (outgoing call). This means any MT calls for a registration with this route type would not be looped to the sip uri in the registration. The use case for using this type would be for example: Call Center for outgoing calls

ROUTE_TYPE_LOOP_MT: Will loop a call only if direction of the call is mobile terminating (incoming call). This means any MO calls for a registration with this route type would not be looped to the sip uri in the registration. The use case for using this type would be for example: Business Phone Systems with BYOD policy (route incoming business calls to personal user devices)

ROUTE_TYPE_INGRESS allows PBX/TAS to place calls to MSISDN attached to the registration of that type. Regular calls to/from that MSISDN are not affected otherwise.

Creating the registration SipBreakOutService.UpsertRegistration(Registration) - registration details select its type, prefixes to use on leg 2 (see above drawing), domain name of the TAS server.

Prefix towards TAS Cisco can provide prefix in INVITE's URI to help TAS to figure out if call came because of the Caller or the Answerer. The prefix is set as follows

Caller has Registration Answerer has Registration Prefix
Yes Yes mobile_originating_prefix
Yes No mobile_originating_prefix
No Yes mobile_terminating_prefix

Maintaining the registration Each SIP Registration has fixed TTL of 3600 seconds since last call to SipBreakOutService.UpsertRegistration() and has to be refreshed by using again SipBreakOutService.UpsertRegistration(Registration) with same parameters.

Deleting the registration To remove registration without waiting for TTL to expire use SipBreakOutService.DeleteRegistration() with the same sip uri used in the original registration.

SIP Transport TLS is used as SIP transport and TAS shall present valid certificate for SIP URI stated in Registration.sip_uri

Media WebRTC style SDPs are used between the core SBC and TAS to encrypt media sessions.

Method Name Request Type Response Type Description
UpsertRegistration UpsertRegistrationRequest UpsertRegistrationResponse Add or replace a registration
DeleteRegistration DeleteRegistrationRequest DeleteRegistrationResponse Delete an existing registration

DeleteRegistrationRequest

The request message to delete a registration

Field Type Label Description
registration Registration Registration to delete

DeleteRegistrationResponse

The response message when attempting to delete a registration

Field Type Label Description
status_code StatusCode The response status for attempting to updating the registration
error_message string Human readable description for what failed or rejected the registration.

Registration

The registration message to define a SIP registration

Field Type Label Description
mobile_originating_prefix string If set to 00 then INVITE sip:+47112334455... becomes INVITE sip:+0047112334455 This field is optional
mobile_terminating_prefix string If set to 00 then INVITE sip:+47112334455... becomes INVITE sip:+0047112334455 This field is optional
sip_uri string sips:example.com or sips:example.com:8888
If you want to use SRV DNS records, then use the domain name without port number
route_type RouteType The route type of the registration
phone_number wgtwo.common.v1.E164 Must be provided if using client access token

UpsertRegistrationRequest

The request message to upsert a registration

Field Type Label Description
registration Registration The registration to add or update.

UpsertRegistrationResponse

The response message when attempting to upsert a registration

Field Type Label Description
status_code StatusCode The response status for attempting to updating the registration
error_message string Human readable description for what failed or rejected the registration.
time_to_live google.protobuf.Duration Time to live for the registration

RouteType

Name Number Description
ROUTE_TYPE_UNSPECIFIED 0 Unspecified/default route type. Do not use.
ROUTE_TYPE_LOOP 1 See SipBreakoutService.
ROUTE_TYPE_FORK 2 See SipBreakoutService.
ROUTE_TYPE_FALLBACK 3 See SipBreakoutService.
ROUTE_TYPE_LOOP_MO 4 See SipBreakoutService.
ROUTE_TYPE_LOOP_MT 5 See SipBreakoutService.
ROUTE_TYPE_INGRESS 6 See SipBreakoutService.

StatusCode

Name Number Description
STATUS_CODE_UNSPECIFIED 0 Unspecified/default route type. Do not use.
STATUS_CODE_OK 1 Registration was successfully updated.
STATUS_CODE_NOT_ACCEPTABLE 2 Registration was not accepted.

Top

wgtwo/sms/v1/sms.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/sms/v1/sms.proto

SmsService

Service to handle sending of SMS messages to and from subscribers.

Method Name Request Type Response Type Description
SendTextFromSubscriber SendTextFromSubscriberRequest SendMessageResponse Send a text SMS message from the subscriber to any number the subscriber can send to.
SendTextToSubscriber SendTextToSubscriberRequest SendMessageResponse Send a text SMS message to the subscriber as any sender address the product has a right to send as.
SendDataToSubscriber SendDataToSubscriberRequest SendMessageResponse Send a data SMS message to the subscriber as any sender address the product has a right to send as.

ApplicationPort

Application ports are used to send data SMS messages to specific applications on the handset. If a reply to the message is sent, it should use the same ports but swap originator and destination port numbers.

Field Type Label Description
originator_port uint32 The originator application port.
destination_port uint32 The destination application port.

SendDataToSubscriberRequest

The request message to send data SMS to a subscriber.

Field Type Label Description
content bytes The binary content of the data SMS. Must be at least 1 byte, and maximum 2000 bytes.
to_subscriber string The destination phone number of the subscriber to receive the message. Must be international number starting with '+'.
from_address string Origin address of the message.

It can either be a:
- a phone number formatted as E.164 starting with '+'.
- a alphanumeric sender ID.
- short form number.
- network specific number.

Typical values here would be to send from your product's name.

Important: Address must be pre-approved by Cisco. See docs on origin addresses for what is allowed.
delivery_deadline google.protobuf.Duration Deadline to which the message needs to be delivered. If this is passed and a delivery is not succeeded, the message delivery will fail. If not set will use the maximum deadline. Maximum is 7 days.
message_class MessageClass The message class to use for the data SMS message.
application_port ApplicationPort The application port for the message.

SendMessageResponse

The response message for sending a SMS.

Field Type Label Description
message_id string An ID representing the message. For events etc related to the message, this ID will be used in the event as identifier.
status SendMessageResponse.SendStatus The response status for attempting to send the message.
description string Human readable description for what failed or rejected the message.
num_fragments uint32 Number of fragments sent. This is because of the underlying SMS protocols only supports sending 140 bytes per message after encoding and packing. This is including extra encoding info and correlation and part handling for multi-fragmented messages.

SendTextFromSubscriberRequest

The request message to send a text SMS from a subscriber.

Field Type Label Description
content string The message text content. Minimum 1 character, maximum 2000 characters. Supports unicode, though completeness is dependent on the receiver handset.
from_subscriber string The subscriber number to send this. The sending product must have a right to send as the subscriber specifically. E.g. operators can only send as their own subscribers, third party products only as subscribers who have enabled the product. Must be international number starting with '+'.
to_address string The destination number of the message. Can be international starting with '+', short form number or network specific numbers.
delivery_deadline google.protobuf.Duration Deadline to which the message needs to be delivered. If this is passed and a delivery is not succeeded, the message delivery will fail. If not set will use the maximum deadline. Maximum is 7 days.

SendTextToSubscriberRequest

The request message to send text SMS to a subscriber.

Field Type Label Description
content string The message text content. Minimum 1 character, maximum 2000 characters. Supports unicode, though completeness is dependent on the receiver handset.
to_subscriber string The destination phone number of the subscriber to receive the message. Must be international number starting with '+'.
from_address string Origin address of the message.

It can either be a:
- a phone number formatted as E.164 starting with '+'.
- a alphanumeric sender ID.
- short form number.
- network specific number.

Typical values here would be to send from your product's name.

Important: Address must be pre-approved by Cisco. See docs on origin addresses for what is allowed.
delivery_deadline google.protobuf.Duration Deadline to which the message needs to be delivered. If this is passed and a delivery is not succeeded, the message delivery will fail. If not set will use the maximum deadline. Maximum is 7 days.

MessageClass

The class of the message.

See https://en.wikipedia.org/wiki/Data_Coding_Scheme#Message_Classes

Name Number Description
MESSAGE_CLASS_UNSPECIFIED 0 No message class specified.
MESSAGE_CLASS_FLASH_MESSAGE 1 CLASS 0 A flash message is a message that is not stored on the device. It is handled immediately or dropped, and also cannot be multi-fragment. Data messages of this type needs a destination application port to designate what app will handle it.
MESSAGE_CLASS_ME_SPECIFIC 2 CLASS 1 Mobile Equipment specific messages are handled by by an application on the handset device itself, e.g. WAP push messages. Data messages of this type needs a destination application port to designate what app will handle it.
MESSAGE_CLASS_SIM_SPECIFIC 3 CLASS 2 Handled by the sim card. SIM updates have special requirements tied to the SIM card itself, and must be signed with a SIM specific private key only known by the operator.
MESSAGE_CLASS_TE_SPECIFIC 4 CLASS 3 Terminal Equipment specific message are handled by the handset itself, or by a SIM application, and may require an application port to designate who will handle it.

SendMessageResponse.SendStatus

Name Number Description
SEND_STATUS_UNSPECIFIED 0
SEND_STATUS_OK 1 Sending the message is accepted. Note that the message is not delivered yet.
SEND_STATUS_REJECT 2 Sending the message is rejected (not allowed). This may be because of subscriber policy limitations, rights of the product or content of the message. See description for details.
SEND_STATUS_ERROR 3 Sending the message failed. This error should be treated as temporary, and sending the message again may work.

Top

wgtwo/subscription/v0/network_info.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/subscription/v0/network_info.proto

NetworkInfoService

Method Name Request Type Response Type Description
GetNetworkInfoForSubscriber GetNetworkInfoForSubscriberRequest GetNetworkInfoForSubscriberResponse Get current network information for subscriber
GetAttachmentAttemptsForSubscriber GetAttachmentAttemptsForSubscriberRequest GetAttachmentAttemptsForSubscriberResponse Get attachment attempts, both failed and successful, for subscriber

AttachmentAttempt

Field Type Label Description
iccid wgtwo.common.v0.Iccid
imsi wgtwo.common.v0.Imsi
timestamp google.protobuf.Timestamp
network_identity wgtwo.common.v0.NetworkIdentity
network_generation wgtwo.common.v0.NetworkGeneration
tadig wgtwo.common.v0.Tadig TADIG code, if present. May be empty.
status Status

GetAttachmentAttemptsForSubscriberRequest

Field Type Label Description
phone_number wgtwo.common.v0.PhoneNumber
filter_by_interval Interval
max_attempts uint32

GetAttachmentAttemptsForSubscriberResponse

Field Type Label Description
attachment_attempts AttachmentAttempt repeated

GetNetworkInfoForSubscriberRequest

Field Type Label Description
phone_number wgtwo.common.v0.PhoneNumber

GetNetworkInfoForSubscriberResponse

Field Type Label Description
network_infos NetworkInfo repeated

Interval

Field Type Label Description
after google.protobuf.Timestamp
before google.protobuf.Timestamp

NetworkInfo

Field Type Label Description
iccid wgtwo.common.v0.Iccid
imsi wgtwo.common.v0.Imsi
timestamp google.protobuf.Timestamp
network_identity wgtwo.common.v0.NetworkIdentity
network_generation wgtwo.common.v0.NetworkGeneration
tadig wgtwo.common.v0.Tadig TADIG code, if present May be empty
msc wgtwo.common.v0.GlobalTitle MSC, if present May be empty
vlr wgtwo.common.v0.GlobalTitle VLR, if present May be empty
sgsn wgtwo.common.v0.GlobalTitle SGSN, if present May be empty
mme wgtwo.common.v0.Fqdn MME, if present May be empty

Status

Field Type Label Description
code Code
description string

Code

Name Number Description
CODE_UNSPECIFIED 0 Is the default value and will not be used.
CODE_OK 1 Indicates that the attachment was successful.
CODE_ABSENT_PROFILE 2 Currently not used.
CODE_ABSENT_SUBSCRIBER 3 Currently not used.
CODE_UNKNOWN_PROFILE 4 Indicates that the subscriber was not allowed to attach because it is not provisioned on the platform.
CODE_BLOCKED_PROFILE 5 Indicates that the subscriber was not allowed to attach because it is inactive/blocked.
CODE_ROAMING_NOT_ALLOWED 6 Indicates that the subscriber was not allowed to attach because it either was missing the roaming services or because the roaming profile of the subscriber did not allow the it to roam at that location.

Top

wgtwo/subscription/v0/subscription_id.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/subscription/v0/subscription_id.proto

Copyright 2022 [Working Group Two]/[Cisco Systems]

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SubscriptionIdService

Method Name Request Type Response Type Description
GetSubscriptionId GetSubscriptionIdRequest GetSubscriptionIdResponse Get globally unique subscription id for a msisdn
GetMsisdn GetMsisdnRequest GetMsisdnResponse Get msisdn for a globally unique subscription id

GetMsisdnRequest

Field Type Label Description
subscription_id wgtwo.common.v0.SubscriptionIdentifier

GetMsisdnResponse

Field Type Label Description
phone_number wgtwo.common.v0.PhoneNumber
status_code wgtwo.common.v0.StatusCode
error_message string

GetSubscriptionIdRequest

Field Type Label Description
phone_number wgtwo.common.v0.PhoneNumber

GetSubscriptionIdResponse

Field Type Label Description
subscription_id wgtwo.common.v0.SubscriptionIdentifier
status_code wgtwo.common.v0.StatusCode
error_message string

Top

wgtwo/subscription/v1/subscription_events.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/subscription/v1/subscription_events.proto

SubscriptionEventService

Service to handle events related to a subscription, and where the subscriber is located. Each event has two operating methods: Stream*Event and Ack*Event. See events.proto for details on subscribing.

Event Description
First Attachment When the subscriber first attaches to the network.
Periodic Country While the subscriber is in a country.
Country Change When the subscriber changes current country location.
Handset Change When the SIM card is moved from one handset to another.
Method Name Request Type Response Type Description
StreamHandsetChangeEvents StreamHandsetChangeEventsRequest StreamHandsetChangeEventsResponse stream Handset Change events are triggered whenever a SIM card is moved from one handset to another.
AckHandsetChangeEvent AckHandsetChangeEventRequest AckHandsetChangeEventResponse Manually ack a handset change event.
StreamFirstAttachmentEvents StreamFirstAttachmentEventsRequest StreamFirstAttachmentEventsResponse stream First Attachment events are triggered whenever a SIM is first attached to the network. It contains the IMSI to distinguish which SIM of the subscriber has been attached.
AckFirstAttachmentEvent AckFirstAttachmentEventRequest AckFirstAttachmentEventResponse Manually ack a first attachment event.
StreamCountryChangeEvents StreamCountryChangeEventsRequest StreamCountryChangeEventsResponse stream Country change events are triggered whenever a SIM changes current country location. It has both the current (new) country and the previous (old) country.

This event is triggered when the previously seen country and the currently seen country are different. Note that subscribers being close to borders, or during travels may generate a lot of CountryChange events. See 'PeriodicCountry' events for an alternative.

For subscribers with multiple SIM cards you will see an event for each SIM (IMSI), as they can move between countries individually.
AckCountryChangeEvent AckCountryChangeEventRequest AckCountryChangeEventResponse Manually ack a country change event.
StreamPeriodicCountryEvents StreamPeriodicCountryEventsRequest StreamPeriodicCountryEventsResponse stream Periodic country events are triggered on a regular basis for each user for each country where they are seen. It is triggered by knowingly seeing the subscriber & handset in a specific country, and for each tenant will be triggered on a regular interval. E.g. if 'Operator X' is configured for a 2 week interval, there will be an event every 14 days (or 336 hours or 1209600 seconds) as long as the subscriber is still seen in that country.

As this event is not always triggered based on the subscriber moving between countries, it does not contain the previously seen country. For getting the real-time movement of the subscriber between countries, use 'CountryChange' event.

This event is triggered:

- When the subscriber first turns on the device and it connects to a network, it will be triggered for the country of the connected network at the same time as the corresponding 'FirstAttachment' event.
- When the subscriber enters a new country (not visited before). This is triggered at the same time as the corresponding 'CountryChange' event.
- When the subscriber is seen in a country, and the 'PeriodicCountry' event for that subscriber and country has not been triggered for the configured time delay.

For subscribers with multiple SIM cards you will see an event for each SIM (IMSI), as they can move between countries individually.
AckPeriodicCountryEvent AckPeriodicCountryEventRequest AckPeriodicCountryEventResponse Manually ack a periodic country event.

AckCountryChangeEventRequest

Request message for acknowledging a country change event.

Field Type Label Description
ack_info wgtwo.events.v1.AckInfo Used to identify the event to acknowledge.

AckCountryChangeEventResponse

Response message for acknowledging a country change event.

Field Type Label Description
ack_status wgtwo.events.v1.AckStatus The status response (success/failure) of the acknowledgement.

AckFirstAttachmentEventRequest

Request message for acknowledging a first attachment event.

Field Type Label Description
ack_info wgtwo.events.v1.AckInfo Used to identify the event to acknowledge.

AckFirstAttachmentEventResponse

Response message for acknowledging a first attachment event.

Field Type Label Description
ack_status wgtwo.events.v1.AckStatus The status response (success/failure) of the acknowledgement.

AckHandsetChangeEventRequest

Request message for acknowledging a handset change event.

Field Type Label Description
ack_info wgtwo.events.v1.AckInfo Used to identify the event to acknowledge.

AckHandsetChangeEventResponse

Response message for acknowledging a handset change event.

Field Type Label Description
ack_status wgtwo.events.v1.AckStatus The status response (success/failure) of the acknowledgement.

AckPeriodicCountryEventRequest

Request message for acknowledging a periodic country event.

Field Type Label Description
ack_info wgtwo.events.v1.AckInfo Used to identify the event to acknowledge.

AckPeriodicCountryEventResponse

Response message for acknowledging a periodic country event.

Field Type Label Description
ack_status wgtwo.events.v1.AckStatus The status response (success/failure) of the acknowledgement.

CountryChangeEvent

The country change event message

Field Type Label Description
number wgtwo.common.v1.E164 The international number of the subscriber.
previous wgtwo.common.v1.Country The country the subscriber moved from.
current wgtwo.common.v1.Country The country the subscriber moved to.

FirstAttachmentEvent

The first attachment event message

Field Type Label Description
number wgtwo.common.v1.E164 The international number of the subscriber.
imsi wgtwo.common.v1.Imsi The IMSI for the SIM card that has been observed. This is PII sensitive information, and needs to be handled with care.

Handset

Handset message

Field Type Label Description
imei_sv wgtwo.common.v1.ImeiSv The International Mobile station Equipment Identity and Software Version number.

HandsetChangeEvent

The handset change event message

Field Type Label Description
number wgtwo.common.v1.E164 The international number of the subscriber.
imsi wgtwo.common.v1.Imsi The IMSI for the SIM card that has been observed. This is PII sensitive information, and needs to be handled with care.
previous Handset The previously stored handset info, may be empty.
current Handset The updated handset info

PeriodicCountryEvent

The periodic country event message

Field Type Label Description
number wgtwo.common.v1.E164 The international number of the subscriber.
imsi wgtwo.common.v1.Imsi The IMSI for the SIM card that has been observed. This is PII sensitive information, and needs to be handled with care.
country wgtwo.common.v1.Country The country for which the SIM card is observed.

StreamCountryChangeEventsRequest

Request message for streaming of country change events.

Field Type Label Description
stream_configuration wgtwo.events.v1.StreamConfiguration Configuration for the stream.

StreamCountryChangeEventsResponse

Response message for streaming of country change events.

Field Type Label Description
metadata wgtwo.events.v1.Metadata Metadata for the stream.
country_change_event CountryChangeEvent The country change event.

StreamFirstAttachmentEventsRequest

Request message for streaming of first attachment events.

Field Type Label Description
stream_configuration wgtwo.events.v1.StreamConfiguration Configuration for the stream.

StreamFirstAttachmentEventsResponse

Response message for streaming of first attachment events.

Field Type Label Description
metadata wgtwo.events.v1.Metadata Metadata for the stream.
first_attachment_event FirstAttachmentEvent The first attachment event.

StreamHandsetChangeEventsRequest

Request message for streaming of handset change events.

Field Type Label Description
stream_configuration wgtwo.events.v1.StreamConfiguration Configuration for the stream.

StreamHandsetChangeEventsResponse

Response message for streaming of handset change events.

Field Type Label Description
metadata wgtwo.events.v1.Metadata Metadata for the stream.
handset_change_event HandsetChangeEvent The handset change event.

StreamPeriodicCountryEventsRequest

Request message for streaming of periodic country events.

Field Type Label Description
stream_configuration wgtwo.events.v1.StreamConfiguration Configuration for the stream.

StreamPeriodicCountryEventsResponse

Response message for streaming of periodic country events.

Field Type Label Description
metadata wgtwo.events.v1.Metadata Metadata for the stream.
periodic_country_event PeriodicCountryEvent The periodic country event.

Top

wgtwo/webterminal/v0/webterminal.proto

Proto definition on GitHub: github.com/working-group-two/wgtwoapis/blob/master/wgtwo/webterminal/v0/webterminal.proto

WebTerminalService

Gateway for WebTerminalProtocol. Requires user's consent to answer and initiate calls.

Method Name Request Type Response Type Description
Pipe WebTerminalMessage stream WebTerminalMessage stream
MultiPipe WebTerminalMessage stream WebTerminalMessage stream

Action

Field Type Label Description
oneof message.toPhone ToPhone

Answer

Field Type Label Description
sdp string

Bye

Error

Field Type Label Description
err Error.Code

Idle

InCall

Field Type Label Description
msisdn wgtwo.common.v0.PhoneNumber

Offer

Field Type Label Description
sdp string
msisdn wgtwo.common.v0.PhoneNumber

Ringing

ToPhone

WebTerminalMessage

Field Type Label Description
oneof message.offer Offer
oneof message.answer Answer
oneof message.ringing Ringing
oneof message.bye Bye
oneof message.idle Idle
oneof message.in_call InCall
oneof message.error Error
oneof message.action Action
call_id string

Error.Code

Name Number Description
UNKNOWN 0
NOT_INCALL 1
TRY_AGAIN 2
INVALID_CALL_ID 3
RATE_LIMIT_HIT 4

Well Known Types

https://protobuf.dev/reference/protobuf/google.protobuf/

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)