.. module:: twilio.util

Twilio Client allows you to make and receive connections in the browser. You can place a call to a phone on the PSTN network, all without leaving your browser. See the Twilio Client Quickstart to get up and running with Twilio Client.

Capability tokens are used by Twilio Client to provide connection security and authorization. The Capability Token documentation explains in depth the purpose and features of these tokens.

:class:`TwilioCapability` is responsible for the creation of these capability tokens. You'll need your Twilio AccountSid and AuthToken.

from twilio.util import TwilioCapability

# Find these values at twilio.com/user/account
account_sid = "AC123123"
auth_token = "secret"

capability = TwilioCapability(account_sid, auth_token)

Before a device running Twilio Client can recieve incoming connections, the instance must first register a name (such as "Alice" or "Bob"). The :meth:`allow_client_incoming` method adds the client name to the capability token.

capability.allow_client_incoming("Alice")

To make an outgoing connection from a Twilio Client device, you'll need to choose a Twilio Application to handle TwiML URLs. A Twilio Application is a collection of URLs responsible for outputting valid TwiML to control phone calls and SMS.

# Twilio Application Sid
application_sid = "APabe7650f654fc34655fc81ae71caa3ff"
capability.allow_client_outgoing(application_sid)

token = capability.generate()

By default, this token will expire in one hour. If you'd like to change the token expiration, :meth:`generate` takes an optional :attr:`expires` argument.

token = capability.generate(expires=600)

This token will now expire in 10 minutes. If you haven't guessed already, :attr:`expires` is expressed in seconds.