{"id":16685933,"url":"https://github.com/zenvia/zenvia-sdk-node","last_synced_at":"2025-03-17T00:32:55.573Z","repository":{"id":35111961,"uuid":"208161602","full_name":"zenvia/zenvia-sdk-node","owner":"zenvia","description":"Zenvia CPaaS SDK for Node.js","archived":false,"fork":false,"pushed_at":"2023-01-06T15:36:30.000Z","size":603,"stargazers_count":29,"open_issues_count":12,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-09T19:48:52.191Z","etag":null,"topics":["api","e-mail","facebook","google-business-messages","hacktoberfest","instagram","javascript","nodejs","rcs","sdk","sms","telegram","typescript","whatsapp"],"latest_commit_sha":null,"homepage":"https://devs.zenvia.com/","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/zenvia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-09-12T23:16:00.000Z","updated_at":"2024-06-25T03:34:28.000Z","dependencies_parsed_at":"2023-01-15T14:04:15.346Z","dependency_job_id":null,"html_url":"https://github.com/zenvia/zenvia-sdk-node","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenvia%2Fzenvia-sdk-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenvia%2Fzenvia-sdk-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenvia%2Fzenvia-sdk-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenvia%2Fzenvia-sdk-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zenvia","download_url":"https://codeload.github.com/zenvia/zenvia-sdk-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243835942,"owners_count":20355611,"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":["api","e-mail","facebook","google-business-messages","hacktoberfest","instagram","javascript","nodejs","rcs","sdk","sms","telegram","typescript","whatsapp"],"created_at":"2024-10-12T15:03:49.136Z","updated_at":"2025-03-17T00:32:55.283Z","avatar_url":"https://github.com/zenvia.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zenvia SDK for Node.js\n\nThis SDK for [Node.js](https://nodejs.org/) was created based on the [Zenvia](https://www.zenvia.com/) [API](https://zenvia.github.io/zenvia-openapi-spec/).\n\n[![License](https://img.shields.io/github/license/zenvia/zenvia-sdk-node.svg)](LICENSE.md)\n[![Build Status](https://travis-ci.com/zenvia/zenvia-sdk-node.svg?branch=master)](https://travis-ci.com/zenvia/zenvia-sdk-node)\n[![Coverage Status](https://coveralls.io/repos/github/zenvia/zenvia-sdk-node/badge.svg?branch=master)](https://coveralls.io/github/zenvia/zenvia-sdk-node?branch=master)\n[![Dependencies](https://img.shields.io/david/zenvia/zenvia-sdk-node.svg)](https://david-dm.org/zenvia/zenvia-sdk-node)\n\n[![NPM](https://nodei.co/npm/@zenvia%2Fsdk.png)](https://nodei.co/npm/@zenvia/sdk/)\n\n[![Twitter Follow](https://img.shields.io/twitter/follow/ZENVIA_.svg?style=social)](https://twitter.com/intent/follow?screen_name=ZENVIA_)\n\n\n\n## Table of Contents\n\n- [Changelog](#changelog)\n- [Features](#features)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Basic Usage](#basic-usage)\n- [Getting Started](#getting-started)\n  - [Sending your first message](#sending-your-first-message)\n  - [Sending a batch](#sending-a-batch)\n  - [Subscribe for messages](#subscribe-for-messages)\n  - [Subscribe for message status](#subscribe-for-message-status)\n  - [Receiving message events and message status events](#receiving-message-events-and-message-status-events)\n  - [Getting message reports](#getting-message-reports)\n  - [Getting flow reports](#getting-a-flow-reports)\n  - [Listing your templates](#listing-your-templates)\n- [Contributing](#contributing)\n- [License](#license)\n\n\n\n## Changelog\n### 2.4.4\n* Fixed \n    * Table of contents marks\n### 2.4.3\n* Added\n    * Card content to Telegram\n    * Replyable text content to Telegram\n### 2.4.2\n* Fixed\n    * NPM publishing for 2.4.X versions\n\n### 2.4.1\n* Added\n    * Card content to Instagram\n    * Carousel content to Instagram\n\n### 2.4.0\n* Added\n    * Card content\n    * Carousel content\n    * Replyable text content\n\n### 2.3.0\n* Added\n    * Email content\n    * Email channel\n    * Google Business Messages (GBM) channel\n    * Telegram channel\n    * Attribute fileName to file content\n\n### 2.2.0\n* Added\n    * Support to custom request headers\n\n### 2.1.1\n* Changed\n    * Fixed template listing\n\n### 2.1.0\n* Added\n    * Instagram channel\n\n### 2.0.0\n* Changed\n    * API endpoint to v2\n\n\n\n## Features\n\n- [x] Text message content\n- [x] File message content\n- [x] Location message content\n- [x] Contacts message content\n- [x] Template message content\n- [x] Email message content\n- [x] Card message content\n- [x] Carousel message content\n- [x] Replyable text message content\n- [x] Send batches\n- [x] Subscription handling\n- [x] Get reports\n- [x] CRUD operations on templates\n- [x] Logging support\n\n\n\n## Prerequisites\n\n* [Sign up](https://www.zenvia.com/) for a Zenvia Account\n* [Node.js](https://nodejs.org/)\n* Generate an API token in the [Zenvia API console](https://app.zenvia.com/home/api)\n* Use you account's User ID as the sender identifier when sending any message. You can find it at the [Zenvia Platform](https://app.zenvia.com/welcome)\n\n\n\n## Installation\n\n```shell\nnpm install @zenvia/sdk\n```\n\n\n\n## Basic Usage\n\n\n```JS\n// ES5\nvar zenvia = require('@zenvia/sdk');\n\n// ES6 or Typescript\nimport * as zenvia from '@zenvia/sdk';\n\n// Initialization with your API token (x-api-token)\nconst client = new zenvia.Client('YOUR_API_TOKEN');\n\n// Choosing the channel\nconst whatsapp = client.getChannel('whatsapp');\n\n// Creating a text content\nconst content = new zenvia.TextContent('some text message here');\n\n// ES6\nwhatsapp.sendMessage('sender-identifier', 'recipient-identifier', content)\n.then(response =\u003e {\n  // do something here\n})\n.catch(error =\u003e {\n  // handle error here\n});\n\n// ES8 or Typescript. NodeJS 7.6.0 or higher\ntry {\n  const response = await whatsapp.sendMessage('sender-identifier', 'recipient-identifier', content);\n  // do something here\n} catch (error) {\n  // handle error here\n}\n```\n\n\n\n## Getting Started\n\nExamples not listed on this section can be found [here](examples).\n\n### Sending your first message\n\nThe content types that can be sent are:\n\n| Name            | Description                                      |\n|-----------------|--------------------------------------------------|\n| TextContent     | Used to send text messages to your customer.     |\n| FileContent     | Used to send file messages to your customer.     |\n| LocationContent | Used to send location messages to your customer. |\n| ContactsContent | Used to send contacts messages to your customer. |\n| TemplateContent | Used to send template messages to your customer. |\n| EmailContent    | Used to send e-mail messages to your customer.   |\n| CardContent     | Used to send card messages to your customer.\n| CarouselContent | Used to send carousel messages to your customer.\n| ReplyableTextContent | Used to send replyable text messages to your customer.\n\nThe channels that can be used to send the content are:\n\n| Channel  | TextContent | FileContent | LocationContent | ContactsContent | TemplateContent | EmailContent | CardContent | CarouselContent | ReplyableTextContent |\n|----------|    :---:    |    :---:    |      :---:      |      :---:      |      :---:      |     :---:    |     :---:   |     :---:       |        :---:         |\n| SMS      | X           |             |                 |                 | X               |              |             |                 |                      |\n| RCS      | X           | X           |                 |                 | X               |              | X           | X               | X                    |\n| WhatsApp | X           | X           | X               | X               | X               |              |             |                 |                      |\n| Facebook | X           | X           |                 |                 |                 |              | X           | X               | X                    |\n| Instagram| X           | X           |                 |                 |                 |              | X           | X               | X                    |\n| Email    |             |             |                 |                 |                 | X            |             |                 |                      |\n| GBM      | X           | X           |                 |                 |                 |              | X           | X               | X                    |\n| Telegram | X           | X           |                 |                 |                 |              |X            |                 | X                    |\n\nUse the `sendMessage` method to messages to your customers.\n\n```js\n// Text message using the SMS channel\nconst client = new Client('YOUR_API_TOKEN');\nconst sms = client.getChannel('sms');\nconst content = new TextContent('some text message');\nconst response = await sms.sendMessage('sender-identifier', 'recipient-identifier', content);\n```\n\nThe response can be an `IMessage` object when successful or an `IError` object when an error occurs.\n\n### Sending a message batch\n\nContent can be sent as a batch. In other words, sending a message with one or more content to one or multiple contacts. You'll need to send a file and comply with the required fields for each type of batch\n\nThe following channels support the following contents to be sent as a batch:\n\n| Channel  | TextContent | TemplateContent |\n|----------|    :---:    |    :---:        |\n| SMS      | X           |                 |\n| WhatsApp |             | X               |\n\nUse the `sendMessageBatch` method to send a batched content to your customers.\n\n```js\n// SMS nessage batch\n\nconst client = new Client('YOUR_API_TOKEN');\nconst smsBatch = {\n  name: 'My first SMS batch',\n  channel: 'sms',\n  message: {\n    from: 'sender-identifier',\n    contents: [\n      {\n        type: 'text',\n        text: 'first text message',\n      },\n      {\n        type: 'text',\n        text: 'second text message',\n      },\n    ],\n  },\n  columnMapper: {\n    \"recipient_header_name\": \"recipient_number_column\",\n    \"name\": \"recipient_name_column\",\n    \"protocol\": \"protocol_column\",\n  },\n};\nconst batch = client.sendMessageBatch('./path/file.csv', smsBatch);\n```\n\nYou may choose to send the content as a string or an array of strings instead of an array of objects. For that, you need to instanciate the `WhatsAppMessageBatch` class to send a batched WhatsApp template message or `SmsMessageBatch` class when sending a batched SMS text message.\n\nAdditionally, instead of sending a file you can send the contents of the file as a stream for both WhatsApp and SMS message batches.\n\n```js\n// WhatsApp message batch\n\n/**\n * stream is core Node.js module\n */\nimport { Readable } from 'stream';\n\nconst client = new Client('SOME_TOKEN');\nconst contents = [\n  'a whatsapp template id',\n  'another whatsapp template id',\n];\nconst columnMapper = {\n  \"recipient_header_name\": \"recipient_number_column\",\n  \"name\": \"recipient_name_column\",\n  \"protocol\": \"protocol_column\",\n};\nconst whatsAppBatch = new WhatsAppMessageBatch(\n  'My first WhatsApp batch',\n  'sender-identifier',\n  contents,\n  columnMapper,\n);\nconst readStream = Readable.from(\"telefone\\n5511999999999\");\nconst batch = client.sendMessageBatch(readstream, whatsAppBatch);\n```\n\nThe response can be an `IBatch` object when successful or an `IError` object when an error occurs.\n\n### Subscribe for messages\n\nUse the `createSubscription` method to create a `MessageSubscription` object for message subscriptions.\n\n```js\nconst client = new Client('YOUR_API_TOKEN');\nconst subscription = new MessageSubscription({\n  url: 'https://your-webhook.company.com'\n},\n{\n  channel: 'sms'\n});\nconst response = await client.createSubscription(subscription);\n```\n\nThe response can be an `ISubscription` object when successful or an `IError` object on errors.\n\n\n### Subscribe for message status\n\nUse the `createSubscription` method to create a `MessageStatusSubscription` object for message status subscriptions.\n\n```js\nconst client = new Client('YOUR_API_TOKEN');\nconst subscription = new MessageStatusSubscription({\n  url: 'https://your-webhook.company.com'\n},\n{\n  channel: 'sms'\n});\nconst response = await client.createSubscription(subscription);\n```\n\nThe response can be an `ISubscription` object when successful or an `IError` object when an error occurs.\n\n\n### Receiving message events and message status events\n\nUse the `WebhookController` class to create your webhook so you can receive message events and message status events. The default port is `3000`.\n\nIf you inform the `client`, `url`, and `channel` fields, a subscription will be created, unless a subscription matching these configuration already exists.\n\nIn the `messageEventHandler` field you will receive the message events and in the `messageStatusEventHandler` field you will receive the message status events.\n\n```js\nconst client = new Client(process.env.ZENVIA_API_TOKEN);\nconst webhook = new WebhookController({\n  messageEventHandler: (messageEvent) =\u003e {\n    console.log('Message event:', messageEvent);\n  },\n  messageStatusEventHandler: (messageStatusEvent) =\u003e {\n    console.log('Message status event:', messageStatusEvent);\n  },\n  client,\n  url: 'https://my-webhook.company.com',\n  channel: 'whatsapp',\n});\nwebhook.init();\n```\n\nTo receive events running the [example](examples/webhook.js) on your machine, we suggest [ngrok](https://ngrok.com/).\n\n\n### Getting message reports\n\nTo get information on how many messages you've sent or have received during a period of time, use the `getEntries` method to list `IReportMessagesEntry` objects as shown below.\n\n```js\nconst client = new Client('YOUR_API_TOKEN');\nconst reportClient = client.getMessagesReportClient();\nconst response = await reportClient.getEntries({\n  startDate: '2020-01-10',\n  endDate: '2020-01-15',\n});\n```\n\nThe response can be an array of `IReportMessagesEntry` objects when successful or an `IError` object when an error occurs.\n\n### Getting flow reports\n\nIn order to get information about the current state of sessions (executions) of flows in a period of time, use the `getEntries` method to list `IReportFlowEntry` objects as shown below.\n\n```js\nconst client = new Client('YOUR_API_TOKEN');\nconst reportClient = client.getFlowReportClient();\nconst response = await reportClient.getEntries({ startDate: '2020-01-10' });\n```\n\nThe response can be an array of `IReportFlowEntry` objects when successful or an `IError` object when an error occurs.\n\n### Listing your templates\n\nYou can execute CRUD operations on templates. For example, use the `listTemplates` method to list an `ITemplate` object.\n\n```js\nconst client = new Client('YOUR_API_TOKEN');\nconst response = await client.listTemplates();\n```\n\nThe response will be an array of `ITemplate` object.\n\n\n\n## Contributing\n\nPull requests are always welcome!\n\nPlease consult the [Contributors' Guide](CONTRIBUTING.md) for more information on contributing.\n\n\n\n## License\n\n[MIT](LICENSE.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenvia%2Fzenvia-sdk-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzenvia%2Fzenvia-sdk-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenvia%2Fzenvia-sdk-node/lists"}