REST API: Usage Triggers

UsageTriggers are webhooks that notify your application of usage thresholds. You can set UsageTriggers for any usage category. UsageTriggers are evaluated frequently - about once a minute - so they can provide timely information to your application. In addition, UsageTriggers can be configured to recur daily, monthly, or yearly so you can create a single UsageTrigger that will track usage every day.

For instance, a UsageTrigger could notify your application if usage cost starts to exceed what you would expect in a day. Or, used in combination with Subaccounts created for each of your end-users, UsageTriggers could notify your application that a particular user has exceeded their allocated monthly usage.

The resource supports POST to make a new UsageTrigger or update an existing UsageTrigger, GET to retrieve existing UsageTriggers, and DELETE to remove an existing trigger.

Triggers Instance Resource

Resource URI

UsageTriggers are scoped under /Usage, and are referenced by their Sid.

/2010-04-01/Accounts/{AccountSid}/Usage/Triggers/{UsageTriggerSid}

Resource Properties

A UsageTrigger is represented by the following properties:

Property Description
Sid The trigger's unique Sid.
DateCreated The date the trigger was created, given as GMT RFC 2822 format.
DateUpdated The date the trigger was last updated, given as GMT RFC 2822 format.
AccountSid The account this trigger monitors.
FriendlyName A user-specified, human-readable name for the trigger.
Recurring How this trigger recurs. Empty for non-recurring triggers. One of daily, monthly, or yearly for recurring triggers. A trigger will only fire once during each recurring period. Recurring periods are in GMT.
UsageCategory The usage category the trigger watches. One of the supported usage categories.
TriggerBy The field in the UsageRecord that fires the trigger. One of count, usage, or price, as described in the UsageRecords documentation.
TriggerValue The value at which the trigger will fire. Must be a positive numeric value.
CurrentValue The current value of the field the trigger is watching.
UsageRecordUri The URI of the UsageRecord this trigger is watching, relative to https://api.twilio.com.
CallbackUrl Twilio will make a request to this url when the trigger fires.
CallbackMethod The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST.
DateFired The date the trigger was last fired, given as GMT RFC 2822 format.
Uri The URI for this resource, relative to https://api.twilio.com.

As soon as the account's usage category crosses the UsageTrigger's TriggerValue during the interval specified, then Twilio will make a request to the CallbackUrl using the HTTP method CallbackMethod with the parameters described below. Twilio guarantees that a UsageTrigger will fire at most once during its recurring interval, and will retry the callback URL 3 times quickly after a 5xx error.

HTTP GET

Returns a repesentation of the UsageTrigger, including the properties above.

Example
Get a UsageTrigger
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4.json \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var trigger = twilio.GetUsageTrigger("UT33c6aeeba34e48f38d6899ea5b765ad4");
    
    Console.WriteLine(trigger.CurrentValue);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.UsageTrigger;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Get an object from its sid. If you do not have a sid,
    // check out the list resource examples on this page
    UsageTrigger trigger = client.getAccount().getUsageTrigger("UT33c6aeeba34e48f38d6899ea5b765ad4");
    System.out.println(trigger.getCurrentValue());
    
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.usage.triggers("UT33c6aeeba34e48f38d6899ea5b765ad4").get(function(err, trigger) {
    console.log(trigger.currentValue);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "your_auth_token"; 
$client = new Services_Twilio($sid, $token);

// Get an object from its sid. If you do not have a sid,
// check out the list resource examples on this page
$trigger = $client->account->usage_triggers->get("UT33c6aeeba34e48f38d6899ea5b765ad4");
echo $trigger->current_value;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

trigger = client.usage.triggers.get("UT33c6aeeba34e48f38d6899ea5b765ad4")
print(trigger.current_value)
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token

# Get an object from its sid. If you do not have a sid,
# check out the list resource examples on this page
@trigger = @client.account.usage.triggers.get("UT33c6aeeba34e48f38d6899ea5b765ad4")
puts @trigger.current_value
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4 \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
Show Output
  • JSON
  • XML
{
   "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records.json?Category=calls", 
   "date_updated": "Sat, 29 Sep 2012 19:47:54 +0000", 
   "date_fired": null, 
   "friendly_name": "Trigger for calls at usage of 500", 
   "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4.json", 
   "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", 
   "callback_method": "POST", 
   "trigger_by": "usage", 
   "sid": "UT33c6aeeba34e48f38d6899ea5b765ad4", 
   "current_value": "21", 
   "date_created": "Sat, 29 Sep 2012 19:45:43 +0000", 
   "callback_url": "http://www.example.com/", 
   "recurring": null, 
   "usage_category": "calls", 
   "trigger_value": "500.000000"
}
<TwilioResponse>
   <UsageTrigger>
      <Sid>UT33c6aeeba34e48f38d6899ea5b765ad4</Sid>
      <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
      <DateCreated>Sat, 29 Sep 2012 19:45:43 +0000</DateCreated>
      <DateUpdated>Sat, 29 Sep 2012 19:47:54 +0000</DateUpdated>
      <DateFired />
      <FriendlyName>Trigger for calls at usage of 500</FriendlyName>
      <UsageCategory>calls</UsageCategory>
      <TriggerBy>usage</TriggerBy>
      <Recurring />
      <TriggerValue>500.000000</TriggerValue>
      <CurrentValue>21</CurrentValue>
      <CallbackUrl>http://www.example.com/</CallbackUrl>
      <CallbackMethod>POST</CallbackMethod>
      <UsageRecordUri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records?Category=calls</UsageRecordUri>
      <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4</Uri>
   </UsageTrigger>
</TwilioResponse>

HTTP POST

Tries to update the UsageTrigger's properties, and returns the updated resource representation if successful. The returned response is identical to that returned when making a GET request.

Optional Parameters

You may specify one or more of the following parameters to update this UsageTrigger's properties. Note that POST parameters are case-sensitive.

Parameter Description
FriendlyName A human-readable name for the trigger.
CallbackUrl Twilio will make a request to this url when the trigger fires.
CallbackMethod The HTTP method Twilio will use when making a request to the CallbackUrl. GET or POST.

Note that it's not currently possible to update the category or value of an existing UsageTrigger. Instead, POST to create a new UsageTrigger, and DELETE to remove the old one.

Example

Change the FriendlyName and CallbackUrl.

Change properties of some UsageTrigger
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4.json \
    -d "FriendlyName=Monthly%20Maximum%20Call%20Usage" \
    -d "CallbackUrl=https://www.example.com/monthly-usage-trigger" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    
    
    twilio.UpdateUsageTrigger("UT33c6aeeba34e48f38d6899ea5b765ad4", "Monthly Maximum Call Usage", "https://www.example.com/monthly-usage-trigger", null);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.UsageTrigger;
import com.twilio.sdk.resource.list.UsageTriggerList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Get an object from its sid. If you do not have a sid,
    // check out the list resource examples on this page
    UsageTrigger trigger = client.getAccount().getUsageTrigger("UT33c6aeeba34e48f38d6899ea5b765ad4");
    // Build a filter for the UsageTriggerList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("FriendlyName", "Monthly Maximum Call Usage"));
    params.add(new BasicNameValuePair("CallbackUrl", "https://www.example.com/monthly-usage-trigger"));
    trigger.update(params);
    
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.usage.triggers("UT33c6aeeba34e48f38d6899ea5b765ad4").update({
    friendlyName: "Monthly Maximum Call Usage",
    callbackUrl: "https://www.example.com/monthly-usage-trigger"
}, function(err, trigger) {
    console.log(trigger.dateFired);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "your_auth_token"; 
$client = new Services_Twilio($sid, $token);

// Get an object from its sid. If you do not have a sid,
// check out the list resource examples on this page
$trigger = $client->account->usage_triggers->get("UT33c6aeeba34e48f38d6899ea5b765ad4");
$trigger->update(array(
        "FriendlyName" => "Monthly Maximum Call Usage",
    "CallbackUrl" => "https://www.example.com/monthly-usage-trigger"
    ));
echo $trigger->date_fired;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

trigger = client.usage.triggers.update("UT33c6aeeba34e48f38d6899ea5b765ad4", friendly_name="Monthly Maximum Call Usage",
    callback_url="https://www.example.com/monthly-usage-trigger")
print(trigger.date_fired)
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token

# Get an object from its sid. If you do not have a sid,
# check out the list resource examples on this page
@trigger = @client.account.usage.triggers.get("UT33c6aeeba34e48f38d6899ea5b765ad4")
@trigger.update(:friendly_name => "Monthly Maximum Call Usage",
    :callback_url => "https://www.example.com/monthly-usage-trigger")
puts @trigger.date_fired
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4 \
    -d "FriendlyName=Monthly%20Maximum%20Call%20Usage" \
    -d "CallbackUrl=https://www.example.com/monthly-usage-trigger" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
Show Output
  • JSON
  • XML
{
   "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records.json?Category=calls", 
   "date_updated": "Sat, 13 Oct 2012 21:24:35 +0000", 
   "date_fired": null, 
   "friendly_name": "Monthly Maximum Call Usage", 
   "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4.json", 
   "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", 
   "callback_method": "POST", 
   "trigger_by": "usage", 
   "sid": "UT33c6aeeba34e48f38d6899ea5b765ad4", 
   "current_value": "21", 
   "date_created": "Sat, 29 Sep 2012 19:45:43 +0000", 
   "callback_url": "https://www.example.com/monthly-usage-trigger", 
   "recurring": null, 
   "usage_category": "calls", 
   "trigger_value": "500.000000"
}
<TwilioResponse>
   <UsageTrigger>
      <Sid>UT33c6aeeba34e48f38d6899ea5b765ad4</Sid>
      <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
      <DateCreated>Sat, 29 Sep 2012 19:45:43 +0000</DateCreated>
      <DateUpdated>Sat, 13 Oct 2012 21:24:35 +0000</DateUpdated>
      <DateFired />
      <FriendlyName>Monthly Maximum Call Usage</FriendlyName>
      <UsageCategory>calls</UsageCategory>
      <TriggerBy>usage</TriggerBy>
      <Recurring />
      <TriggerValue>500.000000</TriggerValue>
      <CurrentValue>21</CurrentValue>
      <CallbackUrl>https://www.example.com/monthly-usage-trigger</CallbackUrl>
      <CallbackMethod>POST</CallbackMethod>
      <UsageRecordUri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records?Category=calls</UsageRecordUri>
      <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UT33c6aeeba34e48f38d6899ea5b765ad4</Uri>
   </UsageTrigger>
</TwilioResponse>

HTTP PUT

Not supported.

HTTP DELETE

Delete this UsageTrigger.

If successful, Twilio will return an HTTP 204 response with no body.

UsageTriggers List Resource

Resource URI

The list resource for all UsageTriggers:

/2010-04-01/Accounts/{AccountSid}/Usage/Triggers

HTTP GET

Returns a list of UsageTrigger resource representations. The list includes paging information.

List Filters

By default, all UsageTriggers are returned. You can filter the list by specifying one or more query parameters. Note that the query parameters are case-sensitive:

Parameter Description
Recurring Only show UsageTriggers that count over this interval. One of daily, monthly, or yearly. To retrieve non-recurring triggers, leave this empty or use alltime.
UsageCategory Only show UsageTriggers that watch this usage category. Must be one of the supported usage categories.
TriggerBy Only show UsageTriggers that trigger by this field in the UsageRecord. Must be one of: count, usage, or price as described in the UsageRecords documentation.
Example: Get All Daily UsageTriggers for Calls
Get Daily UsageTriggers
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers.json \
    -d "Recurring=daily" \
    -d "UsageCategory=calls" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    var triggers = twilio.ListUsageTriggers("daily", "calls", null);
    
    foreach (var trigger in triggers.UsageTriggers)
    {
      Console.WriteLine(trigger.CurrentValue);
    }
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.instance.UsageTrigger;
import com.twilio.sdk.resource.list.UsageTriggerList;
import java.util.HashMap;
import java.util.Map;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the UsageTriggerList
    Map<String, String> params = new HashMap<String, String>();
    
    params.put("Recurring", "daily");
    params.put("UsageCategory", "calls");
    
    UsageTriggerList triggers = client.getAccount().getUsageTriggers(params);
    
    // Loop over triggers and print out a property for each one.
    for (UsageTrigger trigger : triggers) {
      System.out.println(trigger.getCurrentValue());
    }
    
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.usage.triggers.list({ recurring: "daily",
    usageCategory: "calls" }, function(err, data) {
    data.usageTriggers.forEach(function(trigger) {
        console.log(trigger.currentValue);
    });
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "your_auth_token"; 
$client = new Services_Twilio($sid, $token);

// Loop over the list of triggers and echo a property for each one
foreach ($client->account->usage_triggers->getIterator(0, 50, array(
        "Recurring" => "daily",
    "UsageCategory" => "calls"
    )) as $trigger
) {
    echo $trigger->current_value;
}
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

# A list of trigger objects with the properties described above
triggers = client.usage.triggers.list(recurring="daily",
    usage_category="calls")
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token


# Loop over triggers and print out a property for each one
@client.account.usage.triggers.list({
    :recurring => "daily",
    :usage_category => "calls"}).each do |trigger|
    puts trigger.current_value
end
$ curl -G https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers \
    -d "Recurring=daily" \
    -d "UsageCategory=calls" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
Show Output
  • JSON
  • XML
{
   "first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/.json?UsageCategory=calls&Recurring=daily&Page=0&PageSize=50",
   "previous_page_uri": null, 
   "usage_triggers": [
      {
         "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records/Today.json?Category=calls", 
         "date_updated": "Sat, 29 Sep 2012 19:42:57 +0000", 
         "date_fired": null, 
         "friendly_name": "a trigger", 
         "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers//UTc2db285b0cbf4c60a2f1a8db237a5fba.json", 
         "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", 
         "callback_method": "POST", 
         "trigger_by": "count", 
         "sid": "UTc2db285b0cbf4c60a2f1a8db237a5fba", 
         "current_value": "0", 
         "date_created": "Sun, 23 Sep 2012 23:07:29 +0000", 
         "callback_url": "http://www.google.com", 
         "recurring": "daily", 
         "usage_category": "calls", 
         "trigger_value": "0.000000"
      }
   ], 
   "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers.json?UsageCategory=calls&Recurring=daily", 
   "page_size": 50,
   "next_page_uri": null,
   "page": 0
}
<TwilioResponse>
   <UsageTriggers pagesize="50" nextpageuri="" uri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/?UsageCategory=calls&Recurring=daily" firstpageuri="/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/?UsageCategory=calls&Recurring=daily&Page=0&PageSize=50" previouspageuri="" page="0">
      <UsageTrigger>
         <Sid>UTc2db285b0cbf4c60a2f1a8db237a5fba</Sid>
         <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
         <DateCreated>Sun, 23 Sep 2012 23:07:29 +0000</DateCreated>
         <DateUpdated>Sat, 29 Sep 2012 19:42:57 +0000</DateUpdated>
         <DateFired />
         <FriendlyName>a trigger</FriendlyName>
         <UsageCategory>calls</UsageCategory>
         <TriggerBy>count</TriggerBy>
         <Recurring>daily</Recurring>
         <TriggerValue>0.000000</TriggerValue>
         <CurrentValue>0</CurrentValue>
         <CallbackUrl>http://www.google.com</CallbackUrl>
         <CallbackMethod>POST</CallbackMethod>
         <UsageRecordUri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records/Today?Category=calls</UsageRecordUri>
         <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers//UTc2db285b0cbf4c60a2f1a8db237a5fba</Uri>
      </UsageTrigger>
   </UsageTriggers>
</TwilioResponse>

HTTP POST

Creates a new UsageTrigger. Each account can create up to 1,000 UsageTriggers. Currently, UsageTriggers that are no longer active are not deleted automatically. Use DELETE to delete triggers you no longer need.

Required Parameters

Your request must include the following parameters:

Parameter Description
UsageCategory The trigger will watch this usage category. One of the supported usage categories.
TriggerValue The trigger will fire when usage reaches this value. For convenience, you can use an offset like +30, which tells Twilio to create the UsageTrigger with its TriggerValue 30 units higher than the current usage. (just be sure to urlencode the + as %2B).
CallbackUrl Twilio will make a request to this url when the trigger fires.
Optional Parameters

Your request may include the following parameters:

Parameter Description
FriendlyName A human readable description of the new trigger. Maximum 64 characters.
TriggerBy The field in the UsageRecord that will fire the trigger. One of count, usage, or price as described in the UsageRecords documentation. The default is usage.
Recurring To make a recurring trigger that counts over its recurring interval, set this to one of: daily, monthly, or yearly. Omit this to create a non-recurring trigger.
CallbackMethod Twilio will use this HTTP method when making a request to the CallbackUrl. GET or POST. The default is POST.

If successful, Twilio responds with a representation of the new trigger.

Example

Create a new UsageTrigger that will fire when 1,000 SMS messages have been sent.

Create a new UsageTrigger with params
  • C#
  • Java
  • Node.js
  • PHP
  • Python
  • Ruby
  • curl
  • json
  • xml
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers.json \
    -d "TriggerValue=1000" \
    -d "UsageCategory=sms" \
    -d "CallbackUrl=http://www.example.com/" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
// Download the twilio-csharp library from twilio.com/docs/csharp/install
using System;
using Twilio;
class Example 
{
  static void Main(string[] args) 
  {
    // Find your Account Sid and Auth Token at twilio.com/user/account
    string AccountSid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
    string AuthToken = "your_auth_token";
    var twilio = new TwilioRestClient(AccountSid, AuthToken);

    
    var trigger = twilio.CreateUsageTrigger("sms", "1000", "http://www.example.com/");
    
    Console.WriteLine(trigger.Sid);
  }
}
// Install the Java helper library from twilio.com/docs/java/install
import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.TwilioRestException;
import com.twilio.sdk.resource.factory.UsageTriggerFactory;
import com.twilio.sdk.resource.instance.UsageTrigger;
import com.twilio.sdk.resource.list.UsageTriggerList;
import java.util.ArrayList;
import java.util.List;
import org.apache.http.NameValuePair;
import org.apache.http.message.BasicNameValuePair;

public class Example { 

  // Find your Account Sid and Token at twilio.com/user/account
  public static final String ACCOUNT_SID = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
  public static final String AUTH_TOKEN = "your_auth_token";

  public static void main(String[] args) throws TwilioRestException {
    TwilioRestClient client = new TwilioRestClient(ACCOUNT_SID, AUTH_TOKEN);

    // Build a filter for the UsageTriggerList
    List<NameValuePair> params = new ArrayList<NameValuePair>();
    params.add(new BasicNameValuePair("TriggerValue", "1000"));
    params.add(new BasicNameValuePair("UsageCategory", "sms"));
    params.add(new BasicNameValuePair("CallbackUrl", "http://www.example.com/"));
    
    
    UsageTriggerFactory triggerFactory = client.getAccount().getUsageTriggerFactory();
    UsageTrigger trigger = triggerFactory.create(params);
    System.out.println(trigger.getSid());
  }
}
// Download the Node helper library from twilio.com/docs/node/install
// These vars are your accountSid and authToken from twilio.com/user/account
var accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
var authToken = "your_auth_token";
var client = require('twilio')(accountSid, authToken);

client.usage.triggers.create({
    triggerValue: "1000",
    usageCategory: "sms",
    callbackUrl: "http://www.example.com/"
}, function(err, trigger) {
    process.stdout.write(trigger.sid);
});
<?php
// Get the PHP helper library from twilio.com/docs/php/install
require_once('/path/to/twilio-php/Services/Twilio.php'); // Loads the library

// Your Account Sid and Auth Token from twilio.com/user/account
$sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"; 
$token = "your_auth_token"; 
$client = new Services_Twilio($sid, $token);

$trigger = $client->account->usage_triggers->create("sms", "1000", "http://www.example.com/", array());
echo $trigger->sid;
# Download the Python helper library from twilio.com/docs/python/install
from twilio.rest import TwilioRestClient

# Your Account Sid and Auth Token from twilio.com/user/account
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token  = "your_auth_token"
client = TwilioRestClient(account_sid, auth_token)

trigger = client.usage.triggers.create(trigger_value="1000",
    usage_category="sms",
    callback_url="http://www.example.com/")
print(trigger.sid)
# Get twilio-ruby from twilio.com/docs/ruby/install
require 'rubygems'          # This line not needed for ruby > 1.8
require 'twilio-ruby'

# Get your Account Sid and Auth Token from twilio.com/user/account
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'
@client = Twilio::REST::Client.new account_sid, auth_token

trigger = @client.account.usage.triggers.create(:trigger_value => "1000",
    :usage_category => "sms",
    :callback_url => "http://www.example.com/")
puts trigger.usage_category
$ curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers \
    -d "TriggerValue=1000" \
    -d "UsageCategory=sms" \
    -d "CallbackUrl=http://www.example.com/" \
    -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
Show Output
  • JSON
  • XML
{
   "usage_record_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records.json?Category=sms", 
   "date_updated": "Sat, 13 Oct 2012 21:32:30 +0000", 
   "date_fired": null, 
   "friendly_name": "Trigger for sms at usage of 1000", 
   "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UTc142bed7b38c4f8186ef41a309814fd2.json", 
   "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", 
   "callback_method": "POST", 
   "trigger_by": "usage", 
   "sid": "UTc142bed7b38c4f8186ef41a309814fd2", 
   "current_value": "57", 
   "date_created": "Sat, 13 Oct 2012 21:32:30 +0000", 
   "callback_url": "http://www.example.com", 
   "recurring": null, 
   "usage_category": "sms", 
   "trigger_value": "1000.000000"
}
<TwilioResponse>
   <UsageTrigger>
      <Sid>UTc142bed7b38c4f8186ef41a309814fd2</Sid>
      <AccountSid>ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</AccountSid>
      <DateCreated>Sat, 13 Oct 2012 21:32:30 +0000</DateCreated>
      <DateUpdated>Sat, 13 Oct 2012 21:32:30 +0000</DateUpdated>
      <DateFired />
      <FriendlyName>Trigger for sms at usage of 1000</FriendlyName>
      <UsageCategory>sms</UsageCategory>
      <TriggerBy>usage</TriggerBy>
      <Recurring />
      <TriggerValue>1000.000000</TriggerValue>
      <CurrentValue>57</CurrentValue>
      <CallbackUrl>http://www.example.com</CallbackUrl>
      <CallbackMethod>POST</CallbackMethod>
      <UsageRecordUri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Records?Category=sms</UsageRecordUri>
      <Uri>/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Usage/Triggers/UTc142bed7b38c4f8186ef41a309814fd2</Uri>
   </UsageTrigger>
</TwilioResponse>

HTTP PUT

Not Supported.

HTTP DELETE

Not Supported.

UsageTrigger Callbacks

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 fire within a minute of exceeding the usage threshold.

CallbackUrl Request Parameters

The parameters Twilio passes to the UsageTrigger's CallbackUrl are as follows:

Parameter Description
AccountSid Your Twilio account id. It is 34 characters long, and always starts with the letters AC.
UsageTriggerSid The unique identifier of the UsageTrigger that fired.
DateFired When the UsageTrigger fired, in GMT.
Recurring How the UsageTrigger that fired recurs. Empty for non-recurring UsageTriggers. One of daily, monthly, or yearly for recurring UsageTriggers.
UsageCategory The usage category the UsageTrigger watches. One of the supported usage categories.
TriggerBy The field in the UsageRecord that fires the UsageTrigger. One of count, usage, or price as described in the UsageRecords documentation.
TriggerValue The value at which the UsageTrigger will fire.
CurrentUsageValue The current value of the usage the UsageTrigger is watching.
UsageRecordUri The URI of the UsageRecord this UsageTrigger was watching when it fired.
IdempotencyToken A random token generated by Twilio, and guaranteed to be unique for this particular firing of this UsageTrigger. See Best Practices with Usage Trigger Callbacks.

Best Practices with Usage Trigger Callbacks

When implementing a handler for UsageTrigger's CallbackUrl it is possible that your handler may receive HTTP requests more than once. Services that handle duplicate requests and return the same response are called idempotent. We give you an IdempotencyToken that is unique for each Usage Trigger callback.

Example of a Recurring daily Usage Trigger's IdempotencyToken fired on 2012-10-04:

ACed70abd024d3f57a4027b5dc2ca88d5b-FIRES-UTc142bed7b38c4f8186ef41a309814fd2-2012-10-04

You can keep track of the IdempotencyToken to properly handle requests to your service and prevent them from performing same operation twice. For instance, your callback service may send billing notifications via email. For the best possible customer experience, you would want your customer's to only receive the billing notification email once.

You can follow the test-and-set 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 already existing tokens and choose the next appropriate step. In the email example, you would have had already sent the email to your customer, then you would just skip sending the email and reply with an HTTP status code of 200.