{"id":13406573,"url":"https://github.com/twilio/twilio-node","last_synced_at":"2025-05-14T21:02:07.643Z","repository":{"id":7012128,"uuid":"8281084","full_name":"twilio/twilio-node","owner":"twilio","description":"Node.js helper library","archived":false,"fork":false,"pushed_at":"2025-05-05T10:50:38.000Z","size":45102,"stargazers_count":1455,"open_issues_count":44,"forks_count":531,"subscribers_count":88,"default_branch":"main","last_synced_at":"2025-05-07T19:47:42.809Z","etag":null,"topics":["twilio","twilio-api","twiml"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/twilio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2013-02-19T01:38:34.000Z","updated_at":"2025-05-07T19:39:34.000Z","dependencies_parsed_at":"2023-12-14T12:17:07.226Z","dependency_job_id":"2a16b65f-9313-4989-a3b2-dcee523c1d54","html_url":"https://github.com/twilio/twilio-node","commit_stats":{"total_commits":1271,"total_committers":141,"mean_commits":9.01418439716312,"dds":0.8379228953579858,"last_synced_commit":"5dd964e37660b9f848dc3dba670e3289673e5937"},"previous_names":[],"tags_count":292,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twilio%2Ftwilio-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twilio","download_url":"https://codeload.github.com/twilio/twilio-node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254227603,"owners_count":22035667,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["twilio","twilio-api","twiml"],"created_at":"2024-07-30T19:02:33.893Z","updated_at":"2025-05-14T21:02:07.165Z","avatar_url":"https://github.com/twilio.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Node JS"],"sub_categories":[],"readme":"# twilio-node\n\n[![][test-workflow-image]][test-workflow-url]\n[![][npm-version-image]][npm-url]\n[![][npm-install-size-image]][npm-install-size-url]\n[![][npm-downloads-image]][npm-downloads-url]\n\n## Documentation\n\nThe documentation for the Twilio API can be found [here][apidocs].\n\nThe Node library documentation can be found [here][libdocs].\n\n## Versions\n\n`twilio-node` uses a modified version of [Semantic Versioning](https://semver.org) for all changes. [See this document](VERSIONS.md) for details.\n\n### Supported Node.js Versions\n\nThis library supports the following Node.js implementations:\n\n- Node.js 14\n- Node.js 16\n- Node.js 18\n- Node.js 20\n- Node.js lts(22)\n\nTypeScript is supported for TypeScript version 2.9 and above.\n\n\u003e **Warning**\n\u003e Do not use this Node.js library in a front-end application. Doing so can expose your Twilio credentials to end-users as part of the bundled HTML/JavaScript sent to their browser.\n\n## Installation\n\n`npm install twilio` or `yarn add twilio`\n\n### Test your installation\n\nTo make sure the installation was successful, try sending yourself an SMS message, like this:\n\n```js\n// Your AccountSID and Auth Token from console.twilio.com\nconst accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';\nconst authToken = 'your_auth_token';\n\nconst client = require('twilio')(accountSid, authToken);\n\nclient.messages\n  .create({\n    body: 'Hello from twilio-node',\n    to: '+12345678901', // Text your number\n    from: '+12345678901', // From a valid Twilio number\n  })\n  .then((message) =\u003e console.log(message.sid));\n```\n\nAfter a brief delay, you will receive the text message on your phone.\n\n\u003e **Warning**\n\u003e It's okay to hardcode your credentials when testing locally, but you should use environment variables to keep them secret before committing any code or deploying to production. Check out [How to Set Environment Variables](https://www.twilio.com/blog/2017/01/how-to-set-environment-variables.html) for more information.\n\n## OAuth Feature for Twilio APIs\nWe are introducing Client Credentials Flow-based OAuth 2.0 authentication. This feature is currently in beta and its implementation is subject to change.\n\nAPI examples [here](https://github.com/twilio/twilio-node/blob/main/examples/public_oauth.js)\n\nOrganisation API examples [here](https://github.com/twilio/twilio-node/blob/main/examples/orgs_api.js)\n\n## Usage\n\nCheck out these [code examples](examples) in JavaScript and TypeScript to get up and running quickly.\n\n### Environment Variables\n\n`twilio-node` supports credential storage in environment variables. If no credentials are provided when instantiating the Twilio client (e.g., `const client = require('twilio')();`), the values in following env vars will be used: `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`.\n\nIf your environment requires SSL decryption, you can set the path to CA bundle in the env var `TWILIO_CA_BUNDLE`.\n\n### Client Initialization\n\nIf you invoke any V2010 operations without specifying an account SID, `twilio-node` will automatically use the `TWILIO_ACCOUNT_SID` value that the client was initialized with. This is useful for when you'd like to, for example, fetch resources for your main account but also your subaccount. See below:\n\n```javascript\n// Your Account SID, Subaccount SID Auth Token from console.twilio.com\nconst accountSid = process.env.TWILIO_ACCOUNT_SID;\nconst authToken = process.env.TWILIO_AUTH_TOKEN;\nconst subaccountSid = process.env.TWILIO_ACCOUNT_SUBACCOUNT_SID;\n\nconst client = require('twilio')(accountSid, authToken);\nconst mainAccountCalls = client.api.v2010.account.calls.list; // SID not specified, so defaults to accountSid\nconst subaccountCalls = client.api.v2010.account(subaccountSid).calls.list; // SID specified as subaccountSid\n```\n\n### Lazy Loading\n\n`twilio-node` supports lazy loading required modules for faster loading time. Lazy loading is enabled by default. To disable lazy loading, simply instantiate the Twilio client with the `lazyLoading` flag set to `false`:\n\n```javascript\n// Your Account SID and Auth Token from console.twilio.com\nconst accountSid = process.env.TWILIO_ACCOUNT_SID;\nconst authToken = process.env.TWILIO_AUTH_TOKEN;\n\nconst client = require('twilio')(accountSid, authToken, {\n  lazyLoading: false,\n});\n```\n\n### Enable Auto-Retry with Exponential Backoff\n\n`twilio-node` supports automatic retry with exponential backoff when API requests receive an [Error 429 response](https://support.twilio.com/hc/en-us/articles/360044308153-Twilio-API-response-Error-429-Too-Many-Requests-). This retry with exponential backoff feature is disabled by default. To enable this feature, instantiate the Twilio client with the `autoRetry` flag set to `true`.\n\nOptionally, the maximum number of retries performed by this feature can be set with the `maxRetries` flag. The default maximum number of retries is `3`.\n\n```javascript\nconst accountSid = process.env.TWILIO_ACCOUNT_SID;\nconst authToken = process.env.TWILIO_AUTH_TOKEN;\n\nconst client = require('twilio')(accountSid, authToken, {\n  autoRetry: true,\n  maxRetries: 3,\n});\n```\n\n### Set HTTP Agent Options\n\n`twilio-node` allows you to set HTTP Agent Options in the Request Client. This feature allows you to re-use your connections. To enable this feature, instantiate the Twilio client with the `keepAlive` flag set to `true`.\n\nOptionally, the socket timeout and maximum number of sockets can also be set. See the example below:\n\n```javascript\nconst accountSid = process.env.TWILIO_ACCOUNT_SID;\nconst authToken = process.env.TWILIO_AUTH_TOKEN;\n\nconst client = require('twilio')(accountSid, authToken, {\n    timeout: 30000, // HTTPS agent's socket timeout in milliseconds, default is 30000\n    keepAlive: true, // https.Agent keepAlive option, default is false\n    keepAliveMsecs: 1000, // https.Agent keepAliveMsecs option in milliseconds, default is 1000\n    maxSockets: 20, // https.Agent maxSockets option, default is 20\n    maxTotalSockets: 100, // https.Agent maxTotalSockets option, default is 100\n    maxFreeSockets: 5, // https.Agent maxFreeSockets option, default is 5\n    scheduling: \"lifo\", // https.Agent scheduling option, default is 'lifo'\n});\n```\n\n### Specify Region and/or Edge\n\nTo take advantage of Twilio's [Global Infrastructure](https://www.twilio.com/docs/global-infrastructure), specify the target Region and/or Edge for the client:\n\n```javascript\nconst accountSid = process.env.TWILIO_ACCOUNT_SID;\nconst authToken = process.env.TWILIO_AUTH_TOKEN;\n\nconst client = require('twilio')(accountSid, authToken, {\n  region: 'au1',\n  edge: 'sydney',\n});\n```\n\nAlternatively, specify the edge and/or region after constructing the Twilio client:\n\n```javascript\nconst client = require('twilio')(accountSid, authToken);\nclient.region = 'au1';\nclient.edge = 'sydney';\n```\n\nThis will result in the `hostname` transforming from `api.twilio.com` to `api.sydney.au1.twilio.com`.\n\n### Iterate through records\n\nThe library automatically handles paging for you. Collections, such as `calls` and `messages`, have `list` and `each` methods that page under the hood. With both `list` and `each`, you can specify the number of records you want to receive (`limit`) and the maximum size you want each page fetch to be (`pageSize`). The library will then handle the task for you.\n\n`list` eagerly fetches all records and returns them as a list, whereas `each` streams records and lazily retrieves pages of records as you iterate over the collection. You can also page manually using the `page` method.\n\nFor more information about these methods, view the [auto-generated library docs](https://www.twilio.com/docs/libraries/reference/twilio-node/).\n\n```js\n// Your Account SID and Auth Token from console.twilio.com\nconst accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';\nconst authToken = 'your_auth_token';\nconst client = require('twilio')(accountSid, authToken);\n\nclient.calls.each((call) =\u003e console.log(call.direction));\n```\n\n### Enable Debug Logging\n\nThere are two ways to enable debug logging in the default HTTP client. You can create an environment variable called `TWILIO_LOG_LEVEL` and set it to `debug` or you can set the logLevel variable on the client as debug:\n\n```javascript\nconst accountSid = process.env.TWILIO_ACCOUNT_SID;\nconst authToken = process.env.TWILIO_AUTH_TOKEN;\n\nconst client = require('twilio')(accountSid, authToken, {\n  logLevel: 'debug',\n});\n```\n\nYou can also set the logLevel variable on the client after constructing the Twilio client:\n\n```javascript\nconst client = require('twilio')(accountSid, authToken);\nclient.logLevel = 'debug';\n```\n\n### Debug API requests\n\nTo assist with debugging, the library allows you to access the underlying request and response objects. This capability is built into the default HTTP client that ships with the library.\n\nFor example, you can retrieve the status code of the last response like so:\n\n```js\nconst accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';\nconst authToken = 'your_auth_token';\n\nconst client = require('twilio')(accountSid, authToken);\n\nclient.messages\n  .create({\n    to: '+14158675309',\n    from: '+14258675310',\n    body: 'Ahoy!',\n  })\n  .then(() =\u003e {\n    // Access details about the last request\n    console.log(client.lastRequest.method);\n    console.log(client.lastRequest.url);\n    console.log(client.lastRequest.auth);\n    console.log(client.lastRequest.params);\n    console.log(client.lastRequest.headers);\n    console.log(client.lastRequest.data);\n\n    // Access details about the last response\n    console.log(client.httpClient.lastResponse.statusCode);\n    console.log(client.httpClient.lastResponse.body);\n  });\n```\n\n### Handle exceptions\n\nIf the Twilio API returns a 400 or a 500 level HTTP response, `twilio-node` will throw an error including relevant information, which you can then `catch`:\n\n```js\nclient.messages\n  .create({\n    body: 'Hello from Node',\n    to: '+12345678901',\n    from: '+12345678901',\n  })\n  .then((message) =\u003e console.log(message))\n  .catch((error) =\u003e {\n    // You can implement your fallback code here\n    console.log(error);\n  });\n```\n\nor with `async/await`:\n\n```js\ntry {\n  const message = await client.messages.create({\n    body: 'Hello from Node',\n    to: '+12345678901',\n    from: '+12345678901',\n  });\n  console.log(message);\n} catch (error) {\n  // You can implement your fallback code here\n  console.error(error);\n}\n```\n\nIf you are using callbacks, error information will be included in the `error` parameter of the callback.\n\n400-level errors are [normal during API operation](https://www.twilio.com/docs/api/rest/request#get-responses) (\"Invalid number\", \"Cannot deliver SMS to that number\", for example) and should be handled appropriately.\n\n### Use a custom HTTP Client\n\nTo use a custom HTTP client with this helper library, please see the [advanced example of how to do so](./advanced-examples/custom-http-client.md).\n\n### Use webhook validation\n\nSee [example](examples/express.js) for a code sample for incoming Twilio request validation.\n\n## Docker image\n\nThe `Dockerfile` present in this repository and its respective `twilio/twilio-node` Docker image are currently used by Twilio for testing purposes only.\n\n## Getting help\n\nIf you need help installing or using the library, please check the [Twilio Support Help Center](https://support.twilio.com) first, and [file a support ticket](https://twilio.com/help/contact) if you don't find an answer to your question.\n\nIf you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!\n\n## Contributing\n\nBug fixes, docs, and library improvements are always welcome. Please refer to our [Contributing Guide](CONTRIBUTING.md) for detailed information on how you can contribute.\n\n\u003e ⚠️ Please be aware that a large share of the files are auto-generated by our backend tool. You are welcome to suggest changes and submit PRs illustrating the changes. However, we'll have to make the changes in the underlying tool. You can find more info about this in the [Contributing Guide](CONTRIBUTING.md).\n\nIf you're not familiar with the GitHub pull request/contribution process, [this is a nice tutorial](https://gun.io/blog/how-to-github-fork-branch-and-pull-request/).\n\n### Get started\n\nIf you want to familiarize yourself with the project, you can start by [forking the repository](https://help.github.com/articles/fork-a-repo/) and [cloning it in your local development environment](https://help.github.com/articles/cloning-a-repository/). The project requires [Node.js](https://nodejs.org) to be installed on your machine.\n\nAfter cloning the repository, install the dependencies by running the following command in the directory of your cloned repository:\n\n```bash\nnpm install\n```\n\nYou can run the existing tests to see if everything is okay by executing:\n\n```bash\nnpm test\n```\n\nTo run just one specific test file instead of the whole suite, provide a JavaScript regular expression that will match your spec file's name, like:\n\n```bash\nnpm run test:javascript -- -m .\\*client.\\*\n```\n\n[apidocs]: https://www.twilio.com/docs/api\n[libdocs]: https://twilio.github.io/twilio-node\n\n[test-workflow-image]: https://github.com/twilio/twilio-node/actions/workflows/test-and-deploy.yml/badge.svg\n[test-workflow-url]: https://github.com/twilio/twilio-node/actions/workflows/test-and-deploy.yml\n[npm-downloads-image]: https://img.shields.io/npm/dm/twilio.svg\n[npm-downloads-url]: https://npmcharts.com/compare/twilio?minimal=true\n[npm-install-size-image]: https://badgen.net/packagephobia/install/twilio\n[npm-install-size-url]: https://packagephobia.com/result?p=twilio\n[npm-url]: https://npmjs.org/package/twilio\n[npm-version-image]: https://img.shields.io/npm/v/twilio.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwilio%2Ftwilio-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwilio%2Ftwilio-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwilio%2Ftwilio-node/lists"}