# How to listen for Events# OverviewThe event API allows you to subscribe to a variety of different events generated by Cisco's systems.
The examples will start a subscription to voice and voicemail events, which includes call initiated, call ended and
new voicemail received.
# Event typesEvent type Required right CONSENT_REVOKE_EVENT HANDSET_UPDATE_EVENT events.handset_update.subscribe
LOCATION_UPDATE_EVENT events.location.subscribe
ROAMING_EVENT events.roaming.subscribe
SMS_EVENT events.sms.subscribe
SMS_DELIVERY_EVENT events.sms_delivery_report.subscribe
VOICE_EVENT events.voice.subscribe
VOICEMAIL_EVENT events.voicemail.subscribe
# Consent revokeThis event will fire when the OAuth2.0 consent is revoked for a subscription.
It allows the application to cleanup user state. This may either be via our
revoke flow or from customer support.
# Handset updateThis event will fire when a SIM card is used in a new device.
It will contain the previous and current IMEI.
# Location updateThis event will fire when the handset is registering at a new location.
# RoamingThis event will fire on the first location update in a new country.
It will contain the country code and name for the previous and current country.
# SmsThis event will fire every time an SMS is sent or received by the handset.
This contains the from and to address in addition to the actual content of the SMS.
# Sms delivery reportThis event will fire when a SMS delivery report is generated.
This contains the from and to address, and the status for the SMS sent.
# VoiceThis will fire for when a call is initiated, ringing, answered, sent to voicemail or hung up.
It will contain from and to number, call ID and which type of call event it is.
# VoicemailThis will fire when a voicemail is left for a subscription.
It contains from and to number and the ID of the voicemail. The actual content of the voicemail may be retrieved by
a separate API using this ID.
# Listen for eventsSee full example implementation for Java: Maven starter - Listen for events .
#!/usr/bin/env bash
grpcurl \
-H "Authorization: Bearer ${ACCESS_TOKEN} " \
-import-path . \
-proto wgtwo/events/v0/events.proto \
-d '
{
"type": ["VOICE_EVENT"]
}
' \
sandbox.api.wgtwo.com:443 \
wgtwo.events.v0.EventsService.Subscribe
get-events.sh
< dependencies>
< dependency>
< groupId> com.wgtwo.api.v0.grpc</ groupId>
< artifactId> events</ artifactId>
< version> 0.1.6</ version>
</ dependency>
< dependency>
< groupId> com.github.working-group-two.wgtwoapis</ groupId>
< artifactId> utils-grpc</ artifactId>
< version> cca7093</ version>
</ dependency>
</ depenencies>
Snippet
package com. wgtwo. examples. thirdpartydev. events
import com. wgtwo. api. common. Environment
import com. wgtwo. api. v0. events. EventsProto
import com. wgtwo. api. v0. events. EventsServiceGrpc
import com. wgtwo. api. util. auth. Channels
import com. wgtwo. api. util. auth. BearerToken
import io. grpc. stub. StreamObserver
private val channel = Channels. createChannel ( Environment. PRODUCTION)
private val credentials = BearerToken { "MY_ACCESS_TOKEN" }
private val stub = EventsServiceGrpc. newStub ( channel) . withCallCredentials ( credentials)
fun main ( ) {
val request = EventsProto. SubscribeEventsRequest. newBuilder ( )
. addType ( EventsProto. EventType. VOICE_EVENT)
. addType ( EventsProto. EventType. VOICEMAIL_EVENT)
. build ( )
stub. subscribe ( request, object : StreamObserver< EventsProto. SubscribeEventsResponse> {
override fun onNext ( response: EventsProto. SubscribeEventsResponse) {
println ( "Received event of type: ${ response. event. eventCase } " )
}
override fun onError ( throwable: Throwable) {
println ( "Got error: ${ throwable. message } " )
}
override fun onCompleted ( ) {
println ( "Connection closed by the server" )
}
} )
try { Thread. currentThread ( ) . join ( ) } catch ( e: InterruptedException) { }
}
GetEvents.kt # Manual acknowledgeIn the below example we enable manual acknowledgement, and set a custom ack timeout.
Not available.
< dependencies>
< dependency>
< groupId> com.wgtwo.api.v0.grpc</ groupId>
< artifactId> events</ artifactId>
< version> 0.1.6</ version>
</ dependency>
< dependency>
< groupId> com.github.working-group-two.wgtwoapis</ groupId>
< artifactId> utils-grpc</ artifactId>
< version> cca7093</ version>
</ dependency>
< dependency>
< groupId> com.google.protobuf</ groupId>
< artifactId> protobuf-java-util</ artifactId>
< version> 3.11.4</ version>
</ dependency>
</ depenencies>
Snippet
package com. wgtwo. examples. thirdpartydev. events
import com. wgtwo. api. common. Environment
import com. wgtwo. api. v0. events. EventsProto
import com. wgtwo. api. v0. events. EventsServiceGrpc
import com. wgtwo. api. util. auth. Channels
import com. wgtwo. api. util. auth. BearerToken
import io. grpc. stub. StreamObserver
import com. google. protobuf. util. Durations
private val channel = Channels. createChannel ( Environment. PRODUCTION)
private val credentials = BearerToken { "MY_ACCESS_TOKEN" }
private val stub = EventsServiceGrpc. newStub ( channel) . withCallCredentials ( credentials)
fun main ( ) {
val request = EventsProto. SubscribeEventsRequest. newBuilder ( )
. addType ( EventsProto. EventType. VOICE_EVENT)
. addType ( EventsProto. EventType. VOICEMAIL_EVENT)
. setManualAck ( EventsProto. ManualAckConfig. newBuilder ( )
. setEnable ( true )
. setTimeout ( Durations. fromSeconds ( 15 ) )
. build ( )
)
. build ( )
stub. subscribe ( request, object : StreamObserver< EventsProto. SubscribeEventsResponse> {
override fun onNext ( response: EventsProto. SubscribeEventsResponse) {
println ( "Received event of type: ${ response. event. eventCase } " )
acknowledge ( response. event)
}
override fun onError ( throwable: Throwable) {
println ( "Got error: ${ throwable. message } " )
}
override fun onCompleted ( ) {
println ( "Connection closed by the server" )
}
} )
try { Thread. currentThread ( ) . join ( ) } catch ( e: InterruptedException) { }
}
fun acknowledge ( event: EventsProto. Event) {
val request = EventsProto. AckRequest. newBuilder ( )
. setSequence ( event. metadata. sequence)
. setInbox ( event. metadata. ackInbox)
. build ( )
stub. ack ( request, object : StreamObserver< EventsProto. AckResponse> {
override fun onNext ( response: EventsProto. AckResponse) {
println ( "Event successfully acknowledged" )
}
override fun onError ( throwable: Throwable) {
println ( "Error acknowledging event: ${ throwable. message } " )
}
override fun onCompleted ( ) { }
} )
}
GetEventsManualAck.kt # Concepts