REST API: UsageTrigger
A UsageTrigger is a webhook that notifies your application of usage thresholds.
Info Twilio can send your web application an HTTP request when certain events happen, such as an incoming text message to one of your Twilio phone numbers. These requests are called webhooks , or status callbacks . For more, check out our guide to Getting Started with Twilio Webhooks . Find other webhook pages, such as a security guide and an FAQ in the Webhooks section of the docs.
Warning It can take some amount of time for the data used by usage triggers to be reflected in the UsageTriggers evaluations.
Using this resource, you can make or update a new UsageTrigger, fetch information about an existing UsageTrigger or multiple UsageTriggers, or delete an existing UsageTrigger.
You can configure UsageTriggers to recur daily, monthly, or yearly. UsageTriggers are evaluated frequently — about once a minute — to provide timely information to your application.
You can also set UsageTriggers for any usage category. For example, you can create a single UsageTrigger to track daily usage. In this case, a UsageTrigger notifies your application when your cost exceeds a set daily amount. If used together with Subaccounts created for each end-user, then a UsageTrigger would notify your application that a specific user has exceeded an allocated monthly usage.
A UsageTrigger is represented by the following properties:
Resource properties api_version
type: string
The API version used to create the resource.
callback_method
type: enum<http-method>
The HTTP method we use to call callback_url
. Can be: GET
or POST
.
callback_url
type: string<uri>
The URL we call using the callback_method
when the trigger fires.
current_value
type: string
The current value of the field the trigger is watching.
date_created
type: string<date-time-rfc-2822>
date_fired
type: string<date-time-rfc-2822>
date_updated
type: string<date-time-rfc-2822>
friendly_name
type: string
The string that you assigned to describe the trigger.
recurring
type: enum<string>
The frequency of a recurring UsageTrigger. Can be: daily
, monthly
, or yearly
for recurring triggers or empty for non-recurring triggers. A trigger will only fire once during each period. Recurring times are in GMT.
Possible values:
daily
monthly
yearly
alltime
sid
type: SID<UT>
The unique string that that we created to identify the UsageTrigger resource.
Pattern:
^UT[0-9a-fA-F]{32}$
trigger_by
type: enum<string>
trigger_value
type: string
The value at which the trigger will fire. Must be a positive, numeric value.
uri
type: string
The URI of the resource, relative to https://api.twilio.com
.
usage_category
type: enum<string>
The usage category the trigger watches. Must be one of the supported usage categories(link takes you to an external page) .
a2p-registration-fees
agent-conference
amazon-polly
answering-machine-detection
authy-authentications
authy-calls-outbound
authy-monthly-fees
authy-phone-intelligence
authy-phone-verifications
authy-sms-outbound
call-progess-events
calleridlookups
calls
calls-client
calls-globalconference
calls-inbound
calls-inbound-local
calls-inbound-mobile
calls-inbound-tollfree
calls-outbound
calls-pay-verb-transactions
calls-recordings
calls-sip
calls-sip-inbound
calls-sip-outbound
calls-transfers
carrier-lookups
conversations
conversations-api-requests
conversations-conversation-events
conversations-endpoint-connectivity
conversations-events
conversations-participant-events
conversations-participants
cps
flex-usage
fraud-lookups
group-rooms
group-rooms-data-track
group-rooms-encrypted-media-recorded
group-rooms-media-downloaded
group-rooms-media-recorded
group-rooms-media-routed
group-rooms-media-stored
group-rooms-participant-minutes
group-rooms-recorded-minutes
imp-v1-usage
lookups
marketplace
marketplace-algorithmia-named-entity-recognition
marketplace-cadence-transcription
marketplace-cadence-translation
marketplace-capio-speech-to-text
marketplace-convriza-ababa
marketplace-deepgram-phrase-detector
marketplace-digital-segment-business-info
marketplace-facebook-offline-conversions
marketplace-google-speech-to-text
marketplace-ibm-watson-message-insights
marketplace-ibm-watson-message-sentiment
marketplace-ibm-watson-recording-analysis
marketplace-ibm-watson-tone-analyzer
marketplace-icehook-systems-scout
marketplace-infogroup-dataaxle-bizinfo
marketplace-keen-io-contact-center-analytics
marketplace-marchex-cleancall
marketplace-marchex-sentiment-analysis-for-sms
marketplace-marketplace-nextcaller-social-id
marketplace-mobile-commons-opt-out-classifier
marketplace-nexiwave-voicemail-to-text
marketplace-nextcaller-advanced-caller-identification
marketplace-nomorobo-spam-score
marketplace-payfone-tcpa-compliance
marketplace-remeeting-automatic-speech-recognition
marketplace-tcpa-defense-solutions-blacklist-feed
marketplace-telo-opencnam
marketplace-truecnam-true-spam
marketplace-twilio-caller-name-lookup-us
marketplace-twilio-carrier-information-lookup
marketplace-voicebase-pci
marketplace-voicebase-transcription
marketplace-voicebase-transcription-custom-vocabulary
marketplace-whitepages-pro-caller-identification
marketplace-whitepages-pro-phone-intelligence
marketplace-whitepages-pro-phone-reputation
marketplace-wolfarm-spoken-results
marketplace-wolfram-short-answer
marketplace-ytica-contact-center-reporting-analytics
mediastorage
mms
mms-inbound
mms-inbound-longcode
mms-inbound-shortcode
mms-messages-carrierfees
mms-outbound
mms-outbound-longcode
mms-outbound-shortcode
monitor-reads
monitor-storage
monitor-writes
notify
notify-actions-attempts
notify-channels
number-format-lookups
pchat
pchat-users
peer-to-peer-rooms-participant-minutes
pfax
pfax-minutes
pfax-minutes-inbound
pfax-minutes-outbound
pfax-pages
phonenumbers
phonenumbers-cps
phonenumbers-emergency
phonenumbers-local
phonenumbers-mobile
phonenumbers-setups
phonenumbers-tollfree
premiumsupport
proxy
proxy-active-sessions
pstnconnectivity
pv
pv-composition-media-downloaded
pv-composition-media-encrypted
pv-composition-media-stored
pv-composition-minutes
pv-recording-compositions
pv-room-participants
pv-room-participants-au1
pv-room-participants-br1
pv-room-participants-ie1
pv-room-participants-jp1
pv-room-participants-sg1
pv-room-participants-us1
pv-room-participants-us2
pv-rooms
pv-sip-endpoint-registrations
recordings
recordingstorage
rooms-group-bandwidth
rooms-group-minutes
rooms-peer-to-peer-minutes
shortcodes
shortcodes-customerowned
shortcodes-mms-enablement
shortcodes-mps
shortcodes-random
shortcodes-uk
shortcodes-vanity
small-group-rooms
small-group-rooms-data-track
small-group-rooms-participant-minutes
sms
sms-inbound
sms-inbound-longcode
sms-inbound-shortcode
sms-messages-carrierfees
sms-messages-features
sms-messages-features-senderid
sms-outbound
sms-outbound-content-inspection
sms-outbound-longcode
sms-outbound-shortcode
speech-recognition
studio-engagements
sync
sync-actions
sync-endpoint-hours
sync-endpoint-hours-above-daily-cap
taskrouter-tasks
totalprice
transcriptions
trunking-cps
trunking-emergency-calls
trunking-origination
trunking-origination-local
trunking-origination-mobile
trunking-origination-tollfree
trunking-recordings
trunking-secure
trunking-termination
tts-google
turnmegabytes
turnmegabytes-australia
turnmegabytes-brasil
turnmegabytes-germany
turnmegabytes-india
turnmegabytes-ireland
turnmegabytes-japan
turnmegabytes-singapore
turnmegabytes-useast
turnmegabytes-uswest
twilio-interconnect
verify-push
verify-totp
verify-whatsapp-conversations-business-initiated
video-recordings
virtual-agent
voice-insights
voice-insights-client-insights-on-demand-minute
voice-insights-ptsn-insights-on-demand-minute
voice-insights-sip-interface-insights-on-demand-minute
voice-insights-sip-trunking-insights-on-demand-minute
voice-intelligence
voice-intelligence-transcription
voice-intelligence-operators
wireless
wireless-orders
wireless-orders-artwork
wireless-orders-bulk
wireless-orders-esim
wireless-orders-starter
wireless-usage
wireless-usage-commands
wireless-usage-commands-africa
wireless-usage-commands-asia
wireless-usage-commands-centralandsouthamerica
wireless-usage-commands-europe
wireless-usage-commands-home
wireless-usage-commands-northamerica
wireless-usage-commands-oceania
wireless-usage-commands-roaming
wireless-usage-data
wireless-usage-data-africa
wireless-usage-data-asia
wireless-usage-data-centralandsouthamerica
wireless-usage-data-custom-additionalmb
wireless-usage-data-custom-first5mb
wireless-usage-data-domestic-roaming
wireless-usage-data-europe
wireless-usage-data-individual-additionalgb
wireless-usage-data-individual-firstgb
wireless-usage-data-international-roaming-canada
wireless-usage-data-international-roaming-india
wireless-usage-data-international-roaming-mexico
wireless-usage-data-northamerica
wireless-usage-data-oceania
wireless-usage-data-pooled
wireless-usage-data-pooled-downlink
wireless-usage-data-pooled-uplink
wireless-usage-mrc
wireless-usage-mrc-custom
wireless-usage-mrc-individual
wireless-usage-mrc-pooled
wireless-usage-mrc-suspended
wireless-usage-sms
wireless-usage-voice
usage_record_uri
type: string
When an account's usage category crosses a UsageTrigger's TriggerValue
during the specified interval, then Twilio makes a request to the CallbackUrl
using the HTTP method CallbackMethod
with the CallbackUrl
Request parameters.
Twilio guarantees that a UsageTrigger will fire once (at most) during its recurring interval and will quickly retry the callback URL three times after a 5xx error.
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers.json
Each account can create up to 1,000 UsageTriggers. If UsageTrigger creation is successful, Twilio will respond with a representation of the new trigger.
Warning Inactive UsageTriggers will not be deleted automatically.
You need to delete triggers you no longer need. For more information, see Delete a UsageTrigger resource below.
URI parameters Request body parameters CallbackUrl
type: string<uri> Required
The URL we should call using callback_method
when the trigger fires.
TriggerValue
type: string Required
The usage value at which the trigger should fire. For convenience, you can use an offset value such as +30
to specify a trigger_value that is 30 units more than the current usage value. Be sure to urlencode a +
as %2B
.
UsageCategory
type: enum<string> Required
The usage category that the trigger should watch. Use one of the supported usage categories(link takes you to an external page) for this value.
a2p-registration-fees
agent-conference
amazon-polly
answering-machine-detection
authy-authentications
authy-calls-outbound
authy-monthly-fees
authy-phone-intelligence
authy-phone-verifications
authy-sms-outbound
call-progess-events
calleridlookups
calls
calls-client
calls-globalconference
calls-inbound
calls-inbound-local
calls-inbound-mobile
calls-inbound-tollfree
calls-outbound
calls-pay-verb-transactions
calls-recordings
calls-sip
calls-sip-inbound
calls-sip-outbound
calls-transfers
carrier-lookups
conversations
conversations-api-requests
conversations-conversation-events
conversations-endpoint-connectivity
conversations-events
conversations-participant-events
conversations-participants
cps
flex-usage
fraud-lookups
group-rooms
group-rooms-data-track
group-rooms-encrypted-media-recorded
group-rooms-media-downloaded
group-rooms-media-recorded
group-rooms-media-routed
group-rooms-media-stored
group-rooms-participant-minutes
group-rooms-recorded-minutes
imp-v1-usage
lookups
marketplace
marketplace-algorithmia-named-entity-recognition
marketplace-cadence-transcription
marketplace-cadence-translation
marketplace-capio-speech-to-text
marketplace-convriza-ababa
marketplace-deepgram-phrase-detector
marketplace-digital-segment-business-info
marketplace-facebook-offline-conversions
marketplace-google-speech-to-text
marketplace-ibm-watson-message-insights
marketplace-ibm-watson-message-sentiment
marketplace-ibm-watson-recording-analysis
marketplace-ibm-watson-tone-analyzer
marketplace-icehook-systems-scout
marketplace-infogroup-dataaxle-bizinfo
marketplace-keen-io-contact-center-analytics
marketplace-marchex-cleancall
marketplace-marchex-sentiment-analysis-for-sms
marketplace-marketplace-nextcaller-social-id
marketplace-mobile-commons-opt-out-classifier
marketplace-nexiwave-voicemail-to-text
marketplace-nextcaller-advanced-caller-identification
marketplace-nomorobo-spam-score
marketplace-payfone-tcpa-compliance
marketplace-remeeting-automatic-speech-recognition
marketplace-tcpa-defense-solutions-blacklist-feed
marketplace-telo-opencnam
marketplace-truecnam-true-spam
marketplace-twilio-caller-name-lookup-us
marketplace-twilio-carrier-information-lookup
marketplace-voicebase-pci
marketplace-voicebase-transcription
marketplace-voicebase-transcription-custom-vocabulary
marketplace-whitepages-pro-caller-identification
marketplace-whitepages-pro-phone-intelligence
marketplace-whitepages-pro-phone-reputation
marketplace-wolfarm-spoken-results
marketplace-wolfram-short-answer
marketplace-ytica-contact-center-reporting-analytics
mediastorage
mms
mms-inbound
mms-inbound-longcode
mms-inbound-shortcode
mms-messages-carrierfees
mms-outbound
mms-outbound-longcode
mms-outbound-shortcode
monitor-reads
monitor-storage
monitor-writes
notify
notify-actions-attempts
notify-channels
number-format-lookups
pchat
pchat-users
peer-to-peer-rooms-participant-minutes
pfax
pfax-minutes
pfax-minutes-inbound
pfax-minutes-outbound
pfax-pages
phonenumbers
phonenumbers-cps
phonenumbers-emergency
phonenumbers-local
phonenumbers-mobile
phonenumbers-setups
phonenumbers-tollfree
premiumsupport
proxy
proxy-active-sessions
pstnconnectivity
pv
pv-composition-media-downloaded
pv-composition-media-encrypted
pv-composition-media-stored
pv-composition-minutes
pv-recording-compositions
pv-room-participants
pv-room-participants-au1
pv-room-participants-br1
pv-room-participants-ie1
pv-room-participants-jp1
pv-room-participants-sg1
pv-room-participants-us1
pv-room-participants-us2
pv-rooms
pv-sip-endpoint-registrations
recordings
recordingstorage
rooms-group-bandwidth
rooms-group-minutes
rooms-peer-to-peer-minutes
shortcodes
shortcodes-customerowned
shortcodes-mms-enablement
shortcodes-mps
shortcodes-random
shortcodes-uk
shortcodes-vanity
small-group-rooms
small-group-rooms-data-track
small-group-rooms-participant-minutes
sms
sms-inbound
sms-inbound-longcode
sms-inbound-shortcode
sms-messages-carrierfees
sms-messages-features
sms-messages-features-senderid
sms-outbound
sms-outbound-content-inspection
sms-outbound-longcode
sms-outbound-shortcode
speech-recognition
studio-engagements
sync
sync-actions
sync-endpoint-hours
sync-endpoint-hours-above-daily-cap
taskrouter-tasks
totalprice
transcriptions
trunking-cps
trunking-emergency-calls
trunking-origination
trunking-origination-local
trunking-origination-mobile
trunking-origination-tollfree
trunking-recordings
trunking-secure
trunking-termination
tts-google
turnmegabytes
turnmegabytes-australia
turnmegabytes-brasil
turnmegabytes-germany
turnmegabytes-india
turnmegabytes-ireland
turnmegabytes-japan
turnmegabytes-singapore
turnmegabytes-useast
turnmegabytes-uswest
twilio-interconnect
verify-push
verify-totp
verify-whatsapp-conversations-business-initiated
video-recordings
virtual-agent
voice-insights
voice-insights-client-insights-on-demand-minute
voice-insights-ptsn-insights-on-demand-minute
voice-insights-sip-interface-insights-on-demand-minute
voice-insights-sip-trunking-insights-on-demand-minute
voice-intelligence
voice-intelligence-transcription
voice-intelligence-operators
wireless
wireless-orders
wireless-orders-artwork
wireless-orders-bulk
wireless-orders-esim
wireless-orders-starter
wireless-usage
wireless-usage-commands
wireless-usage-commands-africa
wireless-usage-commands-asia
wireless-usage-commands-centralandsouthamerica
wireless-usage-commands-europe
wireless-usage-commands-home
wireless-usage-commands-northamerica
wireless-usage-commands-oceania
wireless-usage-commands-roaming
wireless-usage-data
wireless-usage-data-africa
wireless-usage-data-asia
wireless-usage-data-centralandsouthamerica
wireless-usage-data-custom-additionalmb
wireless-usage-data-custom-first5mb
wireless-usage-data-domestic-roaming
wireless-usage-data-europe
wireless-usage-data-individual-additionalgb
wireless-usage-data-individual-firstgb
wireless-usage-data-international-roaming-canada
wireless-usage-data-international-roaming-india
wireless-usage-data-international-roaming-mexico
wireless-usage-data-northamerica
wireless-usage-data-oceania
wireless-usage-data-pooled
wireless-usage-data-pooled-downlink
wireless-usage-data-pooled-uplink
wireless-usage-mrc
wireless-usage-mrc-custom
wireless-usage-mrc-individual
wireless-usage-mrc-pooled
wireless-usage-mrc-suspended
wireless-usage-sms
wireless-usage-voice
CallbackMethod
type: enum<http-method>
The HTTP method we should use to call callback_url
. Can be: GET
or POST
and the default is POST
.
FriendlyName
type: string
A descriptive string that you create to describe the resource. It can be up to 64 characters long.
Recurring
type: enum<string>
The frequency of a recurring UsageTrigger. Can be: daily
, monthly
, or yearly
for recurring triggers or empty for non-recurring triggers. A trigger will only fire once during each period. Recurring times are in GMT.
Possible values:
daily
monthly
yearly
alltime
TriggerBy
type: enum<string>
_14 // Download the Node helper library from twilio.com/docs/node/install
_14 // These consts are your accountSid and authToken from https://www.twilio.com/console
_14 // To set up environmental variables, see http://twil.io/secure
_14 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14 const authToken = process.env.TWILIO_AUTH_TOKEN;
_14 const client = require('twilio')(accountSid, authToken);
_14 triggerValue: '1000',
_14 usageCategory: 'sms',
_14 callbackUrl: 'http://www.example.com/',
_14 .then(trigger => process.stdout.write(trigger.sid));
_17 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records.json?Category=sms",
_17 "date_updated": "Sat, 13 Oct 2012 21:32:30 +0000",
_17 "friendly_name": "Trigger for sms at usage of 1000",
_17 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UTc142bed7b38c4f8186ef41a309814fd2.json",
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "callback_method": "POST",
_17 "trigger_by": "usage",
_17 "sid": "UTc142bed7b38c4f8186ef41a309814fd2",
_17 "current_value": "57",
_17 "date_created": "Sat, 13 Oct 2012 21:32:30 +0000",
_17 "callback_url": "http://www.example.com",
_17 "usage_category": "sms",
_17 "trigger_value": "1000.000000"
_14 // Download the helper library from https://www.twilio.com/docs/node/install
_14 // Find your Account SID and Auth Token at twilio.com/console
_14 // and set the environment variables. See http://twil.io/secure
_14 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14 const authToken = process.env.TWILIO_AUTH_TOKEN;
_14 const client = require('twilio')(accountSid, authToken);
_14 callbackUrl: 'https://example.com',
_14 triggerValue: 'trigger_value',
_14 usageCategory: 'a2p-registration-fees'
_14 .then(trigger => console.log(trigger.sid));
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "api_version": "2010-04-01",
_18 "callback_method": "GET",
_18 "callback_url": "http://cap.com/streetfight",
_18 "current_value": "0",
_18 "date_created": "Sun, 06 Sep 2015 12:58:45 +0000",
_18 "date_updated": "Sun, 06 Sep 2015 12:58:45 +0000",
_18 "friendly_name": "raphael-cluster-1441544325.86",
_18 "recurring": "yearly",
_18 "sid": "UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "trigger_by": "price",
_18 "trigger_value": "50",
_18 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "usage_category": "totalprice",
_18 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records?Category=totalprice"
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json
URI parameters Sid
type: SID<UT>
The Twilio-provided string that uniquely identifies the UsageTrigger resource to fetch.
Pattern:
^UT[0-9a-fA-F]{32}$
_11 // Download the Node helper library from twilio.com/docs/node/install
_11 // These consts are your accountSid and authToken from https://www.twilio.com/console
_11 // To set up environmental variables, see http://twil.io/secure
_11 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_11 const authToken = process.env.TWILIO_AUTH_TOKEN;
_11 const client = require('twilio')(accountSid, authToken);
_11 .triggers('UT33c6aeeba34e48f38d6899ea5b765ad4')
_11 .then(trigger => trigger.currentValue);
_17 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records.json?Category=calls",
_17 "date_updated": "Sat, 29 Sep 2012 19:47:54 +0000",
_17 "friendly_name": "Trigger for calls at usage of 500",
_17 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4.json",
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "callback_method": "POST",
_17 "trigger_by": "usage",
_17 "sid": "UT33c6aeeba34e48f38d6899ea5b765ad4",
_17 "current_value": "21",
_17 "date_created": "Sat, 29 Sep 2012 19:45:43 +0000",
_17 "callback_url": "http://www.example.com/",
_17 "usage_category": "calls",
_17 "trigger_value": "500.000000"
_10 // Download the helper library from https://www.twilio.com/docs/node/install
_10 // Find your Account SID and Auth Token at twilio.com/console
_10 // and set the environment variables. See http://twil.io/secure
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.usage.triggers('UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .then(trigger => console.log(trigger.friendlyName));
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "api_version": "2010-04-01",
_18 "callback_method": "GET",
_18 "callback_url": "http://cap.com/streetfight",
_18 "current_value": "0",
_18 "date_created": "Sun, 06 Sep 2015 12:58:45 +0000",
_18 "date_updated": "Sun, 06 Sep 2015 12:58:45 +0000",
_18 "friendly_name": "raphael-cluster-1441544325.86",
_18 "recurring": "yearly",
_18 "sid": "UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "trigger_by": "price",
_18 "trigger_value": "50",
_18 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "usage_category": "totalprice",
_18 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records?Category=totalprice"
GET https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers.json
URI parameters Recurring
type: enum<string>
The frequency of recurring UsageTriggers to read. Can be: daily
, monthly
, or yearly
to read recurring UsageTriggers. An empty value or a value of alltime
reads non-recurring UsageTriggers.
Possible values:
daily
monthly
yearly
alltime
TriggerBy
type: enum<string>
UsageCategory
type: enum<string>
The usage category of the UsageTriggers to read. Must be a supported usage categories(link takes you to an external page) .
a2p-registration-fees
agent-conference
amazon-polly
answering-machine-detection
authy-authentications
authy-calls-outbound
authy-monthly-fees
authy-phone-intelligence
authy-phone-verifications
authy-sms-outbound
call-progess-events
calleridlookups
calls
calls-client
calls-globalconference
calls-inbound
calls-inbound-local
calls-inbound-mobile
calls-inbound-tollfree
calls-outbound
calls-pay-verb-transactions
calls-recordings
calls-sip
calls-sip-inbound
calls-sip-outbound
calls-transfers
carrier-lookups
conversations
conversations-api-requests
conversations-conversation-events
conversations-endpoint-connectivity
conversations-events
conversations-participant-events
conversations-participants
cps
flex-usage
fraud-lookups
group-rooms
group-rooms-data-track
group-rooms-encrypted-media-recorded
group-rooms-media-downloaded
group-rooms-media-recorded
group-rooms-media-routed
group-rooms-media-stored
group-rooms-participant-minutes
group-rooms-recorded-minutes
imp-v1-usage
lookups
marketplace
marketplace-algorithmia-named-entity-recognition
marketplace-cadence-transcription
marketplace-cadence-translation
marketplace-capio-speech-to-text
marketplace-convriza-ababa
marketplace-deepgram-phrase-detector
marketplace-digital-segment-business-info
marketplace-facebook-offline-conversions
marketplace-google-speech-to-text
marketplace-ibm-watson-message-insights
marketplace-ibm-watson-message-sentiment
marketplace-ibm-watson-recording-analysis
marketplace-ibm-watson-tone-analyzer
marketplace-icehook-systems-scout
marketplace-infogroup-dataaxle-bizinfo
marketplace-keen-io-contact-center-analytics
marketplace-marchex-cleancall
marketplace-marchex-sentiment-analysis-for-sms
marketplace-marketplace-nextcaller-social-id
marketplace-mobile-commons-opt-out-classifier
marketplace-nexiwave-voicemail-to-text
marketplace-nextcaller-advanced-caller-identification
marketplace-nomorobo-spam-score
marketplace-payfone-tcpa-compliance
marketplace-remeeting-automatic-speech-recognition
marketplace-tcpa-defense-solutions-blacklist-feed
marketplace-telo-opencnam
marketplace-truecnam-true-spam
marketplace-twilio-caller-name-lookup-us
marketplace-twilio-carrier-information-lookup
marketplace-voicebase-pci
marketplace-voicebase-transcription
marketplace-voicebase-transcription-custom-vocabulary
marketplace-whitepages-pro-caller-identification
marketplace-whitepages-pro-phone-intelligence
marketplace-whitepages-pro-phone-reputation
marketplace-wolfarm-spoken-results
marketplace-wolfram-short-answer
marketplace-ytica-contact-center-reporting-analytics
mediastorage
mms
mms-inbound
mms-inbound-longcode
mms-inbound-shortcode
mms-messages-carrierfees
mms-outbound
mms-outbound-longcode
mms-outbound-shortcode
monitor-reads
monitor-storage
monitor-writes
notify
notify-actions-attempts
notify-channels
number-format-lookups
pchat
pchat-users
peer-to-peer-rooms-participant-minutes
pfax
pfax-minutes
pfax-minutes-inbound
pfax-minutes-outbound
pfax-pages
phonenumbers
phonenumbers-cps
phonenumbers-emergency
phonenumbers-local
phonenumbers-mobile
phonenumbers-setups
phonenumbers-tollfree
premiumsupport
proxy
proxy-active-sessions
pstnconnectivity
pv
pv-composition-media-downloaded
pv-composition-media-encrypted
pv-composition-media-stored
pv-composition-minutes
pv-recording-compositions
pv-room-participants
pv-room-participants-au1
pv-room-participants-br1
pv-room-participants-ie1
pv-room-participants-jp1
pv-room-participants-sg1
pv-room-participants-us1
pv-room-participants-us2
pv-rooms
pv-sip-endpoint-registrations
recordings
recordingstorage
rooms-group-bandwidth
rooms-group-minutes
rooms-peer-to-peer-minutes
shortcodes
shortcodes-customerowned
shortcodes-mms-enablement
shortcodes-mps
shortcodes-random
shortcodes-uk
shortcodes-vanity
small-group-rooms
small-group-rooms-data-track
small-group-rooms-participant-minutes
sms
sms-inbound
sms-inbound-longcode
sms-inbound-shortcode
sms-messages-carrierfees
sms-messages-features
sms-messages-features-senderid
sms-outbound
sms-outbound-content-inspection
sms-outbound-longcode
sms-outbound-shortcode
speech-recognition
studio-engagements
sync
sync-actions
sync-endpoint-hours
sync-endpoint-hours-above-daily-cap
taskrouter-tasks
totalprice
transcriptions
trunking-cps
trunking-emergency-calls
trunking-origination
trunking-origination-local
trunking-origination-mobile
trunking-origination-tollfree
trunking-recordings
trunking-secure
trunking-termination
tts-google
turnmegabytes
turnmegabytes-australia
turnmegabytes-brasil
turnmegabytes-germany
turnmegabytes-india
turnmegabytes-ireland
turnmegabytes-japan
turnmegabytes-singapore
turnmegabytes-useast
turnmegabytes-uswest
twilio-interconnect
verify-push
verify-totp
verify-whatsapp-conversations-business-initiated
video-recordings
virtual-agent
voice-insights
voice-insights-client-insights-on-demand-minute
voice-insights-ptsn-insights-on-demand-minute
voice-insights-sip-interface-insights-on-demand-minute
voice-insights-sip-trunking-insights-on-demand-minute
voice-intelligence
voice-intelligence-transcription
voice-intelligence-operators
wireless
wireless-orders
wireless-orders-artwork
wireless-orders-bulk
wireless-orders-esim
wireless-orders-starter
wireless-usage
wireless-usage-commands
wireless-usage-commands-africa
wireless-usage-commands-asia
wireless-usage-commands-centralandsouthamerica
wireless-usage-commands-europe
wireless-usage-commands-home
wireless-usage-commands-northamerica
wireless-usage-commands-oceania
wireless-usage-commands-roaming
wireless-usage-data
wireless-usage-data-africa
wireless-usage-data-asia
wireless-usage-data-centralandsouthamerica
wireless-usage-data-custom-additionalmb
wireless-usage-data-custom-first5mb
wireless-usage-data-domestic-roaming
wireless-usage-data-europe
wireless-usage-data-individual-additionalgb
wireless-usage-data-individual-firstgb
wireless-usage-data-international-roaming-canada
wireless-usage-data-international-roaming-india
wireless-usage-data-international-roaming-mexico
wireless-usage-data-northamerica
wireless-usage-data-oceania
wireless-usage-data-pooled
wireless-usage-data-pooled-downlink
wireless-usage-data-pooled-uplink
wireless-usage-mrc
wireless-usage-mrc-custom
wireless-usage-mrc-individual
wireless-usage-mrc-pooled
wireless-usage-mrc-suspended
wireless-usage-sms
wireless-usage-voice
PageSize
type: integer
How many resources to return in each list page. The default is 50, and the maximum is 1000.
Page
type: integer
The page index. This value is simply for client state.
PageToken
type: string
The page token. This is provided by the API.
_15 // Download the Node helper library from twilio.com/docs/node/install
_15 // These consts are your accountSid and authToken from https://www.twilio.com/console
_15 // To set up environmental variables, see http://twil.io/secure
_15 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15 const authToken = process.env.TWILIO_AUTH_TOKEN;
_15 const client = require('twilio')(accountSid, authToken);
_15 usageCategory: 'calls',
_15 client.usage.triggers.each(filterOpts, trigger =>
_15 console.log(trigger.currentValue)
_27 "first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/.json?UsageCategory=calls&Recurring=daily&Page=0&PageSize=50",
_27 "previous_page_uri": null,
_27 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records/Today.json?Category=calls",
_27 "date_updated": "Sat, 29 Sep 2012 19:42:57 +0000",
_27 "friendly_name": "a trigger",
_27 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers//UTc2db285b0cbf4c60a2f1a8db237a5fba.json",
_27 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_27 "callback_method": "POST",
_27 "trigger_by": "count",
_27 "sid": "UTc2db285b0cbf4c60a2f1a8db237a5fba",
_27 "current_value": "0",
_27 "date_created": "Sun, 23 Sep 2012 23:07:29 +0000",
_27 "callback_url": "http://www.google.com",
_27 "recurring": "daily",
_27 "usage_category": "calls",
_27 "trigger_value": "0.000000"
_27 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers.json?UsageCategory=calls&Recurring=daily",
_27 "next_page_uri": null,
_10 // Download the helper library from https://www.twilio.com/docs/node/install
_10 // Find your Account SID and Auth Token at twilio.com/console
_10 // and set the environment variables. See http://twil.io/secure
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.usage.triggers.list({limit: 20})
_10 .then(triggers => triggers.forEach(t => console.log(t.sid)));
_33 "first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers?PageSize=1&Page=0",
_33 "last_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers?PageSize=1&Page=626",
_33 "next_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers?PageSize=1&Page=1",
_33 "previous_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers?PageSize=1&Page=0",
_33 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers",
_33 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33 "api_version": "2010-04-01",
_33 "callback_method": "GET",
_33 "callback_url": "http://cap.com/streetfight",
_33 "current_value": "0",
_33 "date_created": "Sun, 06 Sep 2015 12:58:45 +0000",
_33 "date_updated": "Sun, 06 Sep 2015 12:58:45 +0000",
_33 "friendly_name": "raphael-cluster-1441544325.86",
_33 "recurring": "yearly",
_33 "sid": "UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33 "trigger_by": "price",
_33 "trigger_value": "50",
_33 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_33 "usage_category": "totalprice",
_33 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records?Category=totalprice"
POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json
Attempts a UsageTrigger's properties update and, if successful, returns the updated resource representation.
The returned response is identical to the returned response of a GET
request.
URI parameters Sid
type: SID<UT>
The Twilio-provided string that uniquely identifies the UsageTrigger resource to update.
Pattern:
^UT[0-9a-fA-F]{32}$
Request body parameters CallbackMethod
type: enum<http-method>
The HTTP method we should use to call callback_url
. Can be: GET
or POST
and the default is POST
.
CallbackUrl
type: string<uri>
The URL we should call using callback_method
when the trigger fires.
FriendlyName
type: string
A descriptive string that you create to describe the resource. It can be up to 64 characters long.
_14 // Download the Node helper library from twilio.com/docs/node/install
_14 // These consts are your accountSid and authToken from https://www.twilio.com/console
_14 // To set up environmental variables, see http://twil.io/secure
_14 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14 const authToken = process.env.TWILIO_AUTH_TOKEN;
_14 const client = require('twilio')(accountSid, authToken);
_14 .triggers('UT33c6aeeba34e48f38d6899ea5b765ad4')
_14 friendlyName: 'Monthly Maximum Call Usage',
_14 callbackUrl: 'https://www.example.com/monthly-usage-trigger',
_14 .then(trigger => console.log(trigger.dateFired));
_17 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records.json?Category=calls",
_17 "date_updated": "Sat, 13 Oct 2012 21:24:35 +0000",
_17 "friendly_name": "Monthly Maximum Call Usage",
_17 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4.json",
_17 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_17 "callback_method": "POST",
_17 "trigger_by": "usage",
_17 "sid": "UT33c6aeeba34e48f38d6899ea5b765ad4",
_17 "current_value": "21",
_17 "date_created": "Sat, 29 Sep 2012 19:45:43 +0000",
_17 "callback_url": "https://www.example.com/monthly-usage-trigger",
_17 "usage_category": "calls",
_17 "trigger_value": "500.000000"
_10 // Download the helper library from https://www.twilio.com/docs/node/install
_10 // Find your Account SID and Auth Token at twilio.com/console
_10 // and set the environment variables. See http://twil.io/secure
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.usage.triggers('UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_10 .update({callbackMethod: 'GET'})
_10 .then(trigger => console.log(trigger.friendlyName));
_18 "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "api_version": "2010-04-01",
_18 "callback_method": "GET",
_18 "callback_url": "http://cap.com/streetfight",
_18 "current_value": "0",
_18 "date_created": "Sun, 06 Sep 2015 12:58:45 +0000",
_18 "date_updated": "Sun, 06 Sep 2015 12:58:45 +0000",
_18 "friendly_name": "raphael-cluster-1441544325.86",
_18 "recurring": "yearly",
_18 "sid": "UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "trigger_by": "price",
_18 "trigger_value": "50",
_18 "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_18 "usage_category": "totalprice",
_18 "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records?Category=totalprice"
DELETE https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{Sid}.json
URI parameters Sid
type: SID<UT>
The Twilio-provided string that uniquely identifies the UsageTrigger resource to delete.
Pattern:
^UT[0-9a-fA-F]{32}$
_10 // Download the helper library from https://www.twilio.com/docs/node/install
_10 // Find your Account SID and Auth Token at twilio.com/console
_10 // and set the environment variables. See http://twil.io/secure
_10 const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10 const authToken = process.env.TWILIO_AUTH_TOKEN;
_10 const client = require('twilio')(accountSid, authToken);
_10 client.usage.triggers('UTXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX').remove();
As soon as the usage value of a UsageTrigger exceeds the TriggerValue
, the trigger will fire and Twilio will make an asynchronous HTTP request to the UsageTrigger's CallbackUrl
. This request will typically take place within a minute of exceeding the usage threshold.
Twilio will pass the following parameters to the UsageTrigger's CallbackUrl
:
Parameter Description AccountSid Your Twilio account id. It is 34 characters long and always starts with the letters AC
UsageTriggerSid Unique identifier of the fired UsageTrigger. DateFired Date when the UsageTrigger fired, in GMT. Recurring How the fired UsageTrigger recurs. For non-recurring UsageTriggers: leave empty. For recurring UsageTriggers: choose daily
, monthly
, or yearly
. UsageCategory Usage category watched by the UsageTrigger: choose from supported usage categories. TriggerBy UsageRecord field that fires the UsageTrigger: choose from count
, usage
, or price
. TriggerValue Value at which the UsageTrigger fired. CurrentValue The current value of the usage watched by the UsageTrigger. UsageRecordUri URI of the UsageRecord that this UsageTrigger watched when it fired. IdempotencyToken A random token generated by Twilio and guaranteed to be unique for this particular firing of this UsageTrigger.
When implementing a handler for UsageTrigger's CallbackUrl
, your handler may receive HTTP requests more than once. Services that handle duplicate requests and return the same response are called Idempotence.
We give you an IdempotencyToken
that is unique for each Usage Trigger callback.
_10 ACed70abd024d3f57a4027b5dc2ca88d5b-FIRES-UTc142bed7b38c4f8186ef41a309814fd2-2012-10-04
You can keep track of your IdempotencyToken
to properly handle requests to your service and prevent a request from performing the same operation twice.
For example, your callback service may send billing notifications via email. For the best possible customer experience, you would want your customers only to receive the billing notification email once.
You can follow the test-and-set (external link) pattern to implement idempotent services. In short, you would test for the existence of the IdempotencyToken
before processing your application's logic. This allows your application to handle existing tokens and choose the next appropriate step.
In the email example, you would have already sent the email to your customer then you would skip sending the email, instead replying with an HTTP status code of 200.