{"id":21414688,"url":"https://github.com/customerio/customerio-node","last_synced_at":"2025-04-05T07:04:28.896Z","repository":{"id":1083928,"uuid":"20968785","full_name":"customerio/customerio-node","owner":"customerio","description":"A node.js client for the Customer.io REST API.","archived":false,"fork":false,"pushed_at":"2024-07-05T09:33:46.000Z","size":508,"stargazers_count":60,"open_issues_count":15,"forks_count":37,"subscribers_count":31,"default_branch":"main","last_synced_at":"2025-03-29T06:03:33.630Z","etag":null,"topics":["customerio","nodejs"],"latest_commit_sha":null,"homepage":"https://customer.io/docs/api/","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/customerio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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}},"created_at":"2014-06-18T16:09:25.000Z","updated_at":"2025-03-20T17:20:19.000Z","dependencies_parsed_at":"2024-05-02T23:39:55.257Z","dependency_job_id":"86830757-0f54-4e7a-8550-374ef3f0efed","html_url":"https://github.com/customerio/customerio-node","commit_stats":{"total_commits":214,"total_committers":36,"mean_commits":5.944444444444445,"dds":0.6728971962616823,"last_synced_commit":"43c088d44cb14721f8b9e94a1db4ab456d1df972"},"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/customerio%2Fcustomerio-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/customerio","download_url":"https://codeload.github.com/customerio/customerio-node/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247299831,"owners_count":20916190,"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":["customerio","nodejs"],"created_at":"2024-11-22T18:32:37.459Z","updated_at":"2025-04-05T07:04:28.876Z","avatar_url":"https://github.com/customerio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=center\u003e\n  \u003ca href=\"https://customer.io\"\u003e\n    \u003cimg src=\"https://avatars.githubusercontent.com/u/1152079?s=200\u0026v=4\" height=\"60\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n[![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blueviolet?logo=gitpod)](https://gitpod.io/#https://github.com/customerio/customerio-node/)\n[![ci](https://github.com/customerio/customerio-node/actions/workflows/main.yml/badge.svg)](https://github.com/customerio/customerio-node/actions/workflows/main.yml)\n\n# Customer.io NodeJS\n\nA node client for the Customer.io Journeys [REST API](https://customer.io/docs/api/). If you're new to Customer.io, we recommend that you integrate with our [Data Pipelines JavaScript client](https://github.com/customerio/cdp-analytics-js) instead.\n\n## Alternative Node runtimes\n\nThis project is developed for and tested against the latest and LTS versions of Node.js. Many runtimes often have subtle differences to the APIs and standard library offered by Node.js. These differences can cause issues when using this library with those runtimes.\n\nIf you would like to use Customer.io with an alternate runtime, we recommend using either our [Track](https://customer.io/docs/api/#tag/trackOverview) and [App](https://customer.io/docs/api/#tag/appOverview) APIs directly using the built-in HTTP client available in your runtime, or our [React Native SDK](https://customer.io/docs/sdk/react-native/getting-started/) if applicable.\n\n## Installation\n\n```\nnpm i --save customerio-node\n```\n\n## Usage\n\n### Creating a new instance\n\nTo start using the library, you first need to create an instance of the CIO class:\n\n```javascript\nconst { TrackClient, RegionUS, RegionEU } = require(\"customerio-node\");\nlet cio = new TrackClient(siteId, apiKey, { region: RegionUS });\n```\n\nBoth the `siteId` and `apiKey` are **required** to create a Basic Authorization header, allowing us to associate the data with your account.\n\nYour account `region` is optional. If you do not specify your region, the default will be the US region (`RegionUS`). If your account is in the EU and you do not provide the correct region, we'll route requests from the US to `RegionEU` accordingly. This may cause data to be logged in the US.\n\nOptionally you can specify `defaults` that will forwarded to the underlying request instance. The [node `http` docs](https://nodejs.org/api/http.html#http_http_request_options_callback) has a list of the possible options.\n\nThis is useful to override the default 10s timeout. Example:\n\n```\nconst cio = new TrackClient('123', 'abc', {\n  timeout: 5000\n});\n```\n\n---\n\n### cio.identify(id, data)\n\nCreating a person is as simple as identifying them with this call. You can also use this method to update a persons data.\n\n```\ncio.identify(1, {\n  email: 'customer@example.com',\n  created_at: 1361205308,\n  first_name: 'Bob',\n  plan: 'basic'\n});\n```\n\n#### Options\n\n- **id**: String or number (required)\n- **data**: Object (optional)\n  - _email_ is a required key if you intend to send email messages\n  - _created_at_ is a required key if you want to segment based on signed up/created date\n\n#### Updating identifiers\n\nIf you want to update an identifier for an existing profile, you must reference them using their `cio_id` in the format `cio_\u003ccio_id_value\u003e`. Using anything else will result in an attribute update failure in Customer.io. You can read more about [updating customers](https://customer.io/docs/api/#operation/identify) on our API documentation.\n\n```\ncio.identify(`cio_${customer.cio_id}`, {\n  email: 'new_email@example.com'\n});\n```\n\n---\n\n### cio.destroy(id)\n\nThis will delete a person from Customer.io.\n\n```\ncio.destroy(1);\n```\n\n#### Options\n\n- **id**: String or number (required)\n\n#### Attention!\n\nThis method will only delete a person and not suppress them. This means they can be readded.\nIf you need to suppress a person, please use [`cio.suppress`](https://github.com/customerio/customerio-node#ciosuppressid).\n\n---\n\n### Merge Customers\n\nWhen you merge two people, you pick a primary person and merge a secondary, duplicate person into it. The primary person remains after the merge and the secondary is deleted. This process is permanent: you cannot recover the secondary person.\n\nThe first and third parameters represent the identifier for the primary and secondary people respectively—one of `id`, `email`, or `cio_id`. The second and fourth parameters are the identifier values for the primary and secondary people respectively.\n\n```javascript\n// cio.mergeCustomers(\"primaryType\", \"primaryIdentifier\", \"secondaryType\", \"secondaryIdentifier\")\n// primaryType / secondaryType are one of \"id\", \"email\", or \"cio_id\"\n// primaryIdentifier / secondaryIdentifier are the identifier value corresponding to the type.\ncio.mergeCustomers(IdentifierType.Id, \"cool.person@company.com\", IdentifierType.Email, \"cperson@gmail.com\");\n```\n\n#### Options\n\n- **primaryType**: One of the ID types - \"id\" / \"email\" / \"cio_id\" (required)\n- **primaryIdentifier**: Primary profile Identifier, String or number (required)\n- **secondaryType**: One of the ID types - \"id\" / \"email\" / \"cio_id\" (required)\n- **secondaryIdentifier**: Secondary profile Identifier, String or number (required)\n\n---\n\n### cio.track(id, data)\n\nThe track method will trigger events within Customer.io. Customer.io requires a name key/value pair in you data object when sending data along with your event.\n\n**Simple event tracking**\n\n```javascript\ncio.track(1, { name: \"updated\" });\n```\n\n**Sending data with an event**\n\n```javascript\ncio.track(1, {\n  name: \"purchase\",\n  data: {\n    price: \"23.45\",\n    product: \"socks\",\n  },\n});\n```\n\n#### Options\n\n- **id**: String or number (required)\n- **data**: Object (required)\n  - _name_ is a required key on the Object\n  - _data_ is an optional key for additional data sent over with the event\n\n---\n\n### cio.trackAnonymous(anonymous_id, data)\n\nTrack an anonymous event. An anonymous event is an event associated with a person you haven't identified, requiring an `anonymous_id` representing the unknown person and an event `name`. When you identify a person, you can set their `anonymous_id` attribute. If [event merging](https://customer.io/docs/anonymous-events/#turn-on-merging) is turned on in your workspace, and the attribute matches the `anonymous_id` in one or more events that were logged within the last 30 days, we associate those events with the person.\n\nAnonymous events cannot trigger campaigns. If you associate an event with a person within 72 hours of the event timestamp, however, a formerly anonymous event can trigger a campaign.\n\n```javascript\ncio.trackAnonymous(anonymous_id, {\n  name: \"updated\",\n  data: {\n    updated: true,\n    plan: \"free\",\n  },\n});\n```\n\n#### Anonymous invite events\n\nIf you previously sent [invite events](https://customer.io/docs/anonymous-invite-emails/), you can achieve the same functionality by sending an anonymous event with an empty string for the anonymous identifier. To send anonymous invites, your event _must_ include a `recipient` attribute.\n\n```javascript\ncio.trackAnonymous(\"\", {\n  name: \"invite\",\n  data: {\n    name: \"Alex\",\n    recipient: \"alex.person@example.com\",\n  },\n});\n```\n\n#### Options\n\n- **anonymous_id**: String or number (required)\n- **data**: Object (required)\n  - _name_ is a required key on the Object\n  - _data_ is an optional key for additional data sent over with the event\n\n---\n\n### cio.trackPageView(id, url)\n\nSending a page event includes sending over the customers id and the name of the page.\n\n```javascript\ncio.trackPageView(1, \"/home\");\n```\n\n#### Options\n\n- **id**: String or number (required)\n- **url**: String (required)\n\n### cio.addDevice(id, device_id, platform, data)\n\nAdd a device to send push notifications.\n\n```javascript\ncio.addDevice(1, \"device_id\", \"ios\", { primary: true });\n```\n\n#### Options\n\n- **customer_id**: String or number (required)\n- **device_id**: String (required)\n- **platform**: String (required)\n- **data**: Object (optional)\n\n### cio.deleteDevice(id, device_id)\n\nDelete a device to remove it from the associated customer and stop sending push notifications to it.\n\n```javascript\ncio.deleteDevice(1, \"device_token\");\n```\n\n#### Options\n\n- **customer_id**: String or number (required)\n- **device_token**: String (required)\n\n### cio.suppress(id)\n\nSuppress a customer.\n\n```javascript\ncio.suppress(1);\n```\n\n#### Options\n\n- **customer_id**: String or number (required)\n\n### cio.unsuppress(id)\n\nUnsuppress a customer.\n\n```javascript\ncio.unsuppress(1);\n```\n\n#### Options\n\n- **customer_id**: String or number (required)\n\n### Using Promises\n\nAll calls to the library will return a native promise, allowing you to chain calls as such:\n\n```javascript\nconst customerId = 1;\n\ncio.identify(customerId, { first_name: \"Finn\" }).then(() =\u003e {\n  return cio.track(customerId, {\n    name: \"updated\",\n    data: {\n      updated: true,\n      plan: \"free\",\n    },\n  });\n});\n```\n\nor use `async/await`:\n\n```javascript\nconst customerId = 1;\n\nawait cio.identify(customerId, { first_name: \"Finn\" });\n\nreturn cio.track(customerId, {\n  name: \"updated\",\n  data: {\n    updated: true,\n    plan: \"free\",\n  },\n});\n```\n\n### Transactional API\n\nTo use the Customer.io [Transactional API](https://customer.io/docs/transactional-api), import our API client and initialize it with an [app key](https://customer.io/docs/managing-credentials#app-api-keys) and create a request object of your message type.\n\n#### Email\n\nCreate a new `SendEmailRequest` object containing:\n\n- `transactional_message_id`: the ID of the transactional message you want to send, or the `body`, `from`, and `subject` of a new message.\n- `to`: the email address of your recipients\n- an `identifiers` object containing the email and/or `id` of your recipient. If the person you reference by email or ID does not exist, Customer.io creates them.\n- a `message_data` object containing properties that you want reference in your message using Liquid.\n- You can also send attachments with your message with `attach`, but you need to read the file to a buffer (with `fs.readFileSync`, for example); you cannot attach raw, base64-encoded data directly from a variable.\n\nUse `sendEmail` referencing your request to send a transactional message. [Learn more about transactional messages and `SendEmailRequest` properties](https://customer.io/docs/transactional-api).\n\n```javascript\nconst fs = require(\"fs\");\nconst { APIClient, SendEmailRequest, RegionUS, RegionEU } = require(\"customerio-node\");\nconst api = new APIClient(\"app-key\", { region: RegionUS });\n\nconst request = new SendEmailRequest({\n  to: \"person@example.com\",\n  transactional_message_id: \"3\",\n  message_data: {\n    name: \"Person\",\n    items: {\n      name: \"shoes\",\n      price: \"59.99\",\n    },\n    products: [],\n  },\n  identifiers: {\n    email: \"person@example.com\",\n  },\n});\n\n// (optional) attach a file to your message.\n// Note that you need to read the file to a buffer;\n// you can't simply attach raw, base64-encoded data.\nrequest.attach(\"receipt.pdf\", fs.readFileSync(\"receipt.pdf\"));\n\napi\n  .sendEmail(request)\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.log(err.statusCode, err.message));\n```\n\n#### Push\n\nCreate a new `SendPushRequest` object containing:\n\n- `transactional_message_id`: the ID or trigger name of the transactional message you want to send.\n- an `identifiers` object containing the `id` or `email` of your recipient. If the profile does not exist, Customer.io will create it.\n\nUse `sendPush` referencing your request to send a transactional message. [Learn more about transactional messages and `sendPushRequest` properties](https://customer.io/docs/transactional-api).\n\n```javascript\nconst { APIClient, SendPushRequest, RegionUS, RegionEU } = require(\"customerio-node\");\nconst api = new APIClient(\"app-key\", { region: RegionUS });\n\nconst request = new SendPushRequest({\n  transactional_message_id: \"3\",\n  message_data: {\n    name: \"Person\",\n    items: {\n      name: \"shoes\",\n      price: \"59.99\",\n    },\n    products: [],\n  },\n  identifiers: {\n    id: \"2\",\n  },\n});\n\napi\n  .sendPush(request)\n  .then((res) =\u003e console.log(res))\n  .catch((err) =\u003e console.log(err.statusCode, err.message));\n```\n\n### api.triggerBroadcast(campaign_id, data, recipients)\n\nTrigger an email broadcast using the email campaign's id. You can also optionally pass along custom data that will be merged with the liquid template, and additional conditions to filter recipients.\n\n```javascript\napi.triggerBroadcast(1, { name: \"foo\" }, { segment: { id: 7 } });\n```\n\nYou can also use emails or ids to select recipients, and pass optional API parameters such as `email_ignore_missing`.\n\n```javascript\napi.triggerBroadcast(1, { name: \"foo\" }, { emails: [\"example@emails.com\"], email_ignore_missing: true });\n```\n\n[You can learn more about the available recipient fields here](https://customer.io/docs/api/#operation/triggerBroadcast).\n\n#### Options\n\n- **id**: String or number (required)\n- **data**: Object (optional)\n- **recipients**: Object (optional)\n\n### api.getCustomersByEmail(email)\n\nReturns customer object with given email.\n\n```javascript\napi.getCustomersByEmail(\"test@test.com\");\n```\n\n[You can learn more about the available recipient fields here](https://customer.io/docs/api/#operation/getPeopleEmail).\n\n#### Options\n\n- **email**: String (required)\n\n### api.getAttributes(id, id_type)\n\nReturns a list of attributes for a customer profile.\n\n```javascript\napi.getAttributes(\"1\", \"id\");\n```\n\nOR\n\n```javascript\nconst { IdentifierType } = require(\"customerio-node\");\n\napi.getAttributes(\"1\", IdentifierType.ID);\n```\n\n[You can learn more about the available recipient fields here](https://customer.io/docs/api/#operation/getPersonAttributes).\n\n#### Options\n\n- **id**: Customer identifier, String or number (required)\n- **id_type**: One of the ID types - \"id\" / \"email\" / \"cio_id\" (default is \"id\")\n\n### api.listExports()\n\nReturn a list of your exports. Exports are point-in-time people or campaign metrics.\n\n```javascript\napi.listExports();\n```\n\n### api.getExport(export_id)\n\nReturn information about a specific export.\n\n```javascript\napi.getExport(1);\n```\n\n#### Options\n\n- **export_id**: String or number (required)\n\n### api.downloadExport(export_id)\n\nThis endpoint returns a signed link to download an export. The link expires after 15 minutes.\n\n```javascript\napi.downloadExport(1);\n```\n\n#### Options\n\n- **export_id**: String or number (required)\n\n### api.createCustomersExport(filters)\n\nProvide filters and attributes describing the customers you want to export. This endpoint returns export metadata; use the /exports/{export_id}/endpoint to download your export.\n\n```javascript\napi.createCustomersExport({\n  filters: {\n    and: [\n      {\n        segment: {\n          id: 3,\n        },\n      },\n    ],\n  },\n});\n```\n\n#### Options\n\n- **filters**: Object (required)\n\nYou can read more about the filter object syntax on the [export customer data](https://customer.io/docs/api/#operation/exportPeopleData) docs.\n\n### api.createDeliveriesExport(newsletter_id, options)\n\nProvide filters and attributes describing the customers you want to export. This endpoint returns export metadata; use the /exports/{export_id}/endpoint to download your export.\n\n```javascript\napi.createDeliveriesExport(1, {\n  start: 1666950084,\n  end: 1666950084,\n  attributes: [\"attr_one\"],\n  metric: \"attempted\",\n  drafts: false,\n});\n```\n\n#### Options\n\n- **newsletter_id**: String or number (required)\n- **options**: Object\n\nYou can read more about the available options on the [export deliveries data](https://customer.io/docs/api/#operation/exportDeliveriesData) docs.\n\n## Further examples\n\nWe've included functional examples in the [examples/ directory](https://github.com/customerio/customerio-node/tree/main/examples) of the repo to further assist in demonstrating how to use this library to integrate with Customer.io\n\n## Tests\n\n```bash\nnpm install \u0026\u0026 npm test\n```\n\n## License\n\nReleased under the MIT license. See file [LICENSE](LICENSE) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcustomerio%2Fcustomerio-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcustomerio%2Fcustomerio-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcustomerio%2Fcustomerio-node/lists"}