# Node.js ## Setup To be able to use TextFlow for sending an SMS or user verification, you first have to [register an account](https://textflow.me), after that you are going to get a free API key with two free SMS, which you can use to send SMS or verify user request anywhere in the world. After you have registered an account, your API key will be available on the [API console](https://textflow.me/api). After you have your API key, you need to install the `textflow.js` npm package: ```bash npm install textflow.js ``` Next thing you have to do is just to load the library and supply your API key. ```javascript const textflow = require("textflow.js"); textflow.useKey("YOUR_API_KEY"); ``` ## Sending an SMS Once you have [initialized the library](#setup), you can easily send a simple SMS by using the `sendSMS` function. ```javascript textflow.sendSMS("+11234567890", "Dummy message text..."); ``` You can also provide the callback, or await the promise that the function returns, so that you can handle the result, which contains the information if the message was successfully sent. ```javascript // Providing the custom callback textflow.sendSMS("+11234567890", "Dummy message text...", (result) => { if (result.ok) { console.log("SUCCESS"); } }) // Awaiting promise inside of async function let result = await textflow.sendSMS("+11234567890", "Dummy message text..."); if (result.ok) { console.log("SUCCESS"); } ``` `result` is a JavaScript object, with the following structure: ```javascript // Example result of a successfully sent message { ok: true, // true if and only if the message was successfully sent status: 200, message: 'Message sent successfully', data: { to: '+11234567890', content: 'Dummy message text...', country_code: 'United States', price: 0.15, timestamp: 1676842652256 } } // Example result of an unsuccessfully sent message { ok: false, status: 400, message: 'Invalid API key or user id.' //This can be different for other errors } ``` ## User verification There are two functions that you should call on your back-end during the user verification process, but firstly you should make sure that you have [set up everything correctly](#setup). `sendVerificationSMS` is used to send user the verification code, while the `verifyCode` is used to check if the code that the user has entered is valid. When you call the `sendVerificationSMS` function, we will send an SMS to the specified phone number. It should be the phone number that you want to verify, e.g. the phone number the user has entered in your app. After sending the verification SMS, you can show the user a form where he should enter the verification code that he should have got in the SMS. When he submits the code, you should call the `verifyCode` function and supply his phone number (which he can send again when submitting the code) along with the code that you want verified. That way, you do not have to worry about keeping data about phone verification in your database, because we are doing it for you. Here is the pseudocode for the whole process: ```javascript //User has sent his phone number for verification textflow.sendVerificationSMS("+11234567890", verificationOptions); //Show him the code submission form //The user has submitted the code let result = await textflow.verifyCode("+11234567890", "USER_ENTERED_CODE"); if(result.valid) console.log("Verified!"); ``` `VerificationOptions` the optional argument for the `sendVerificationSMS` function. It contains the parameters of the verification code that should be sent: `service_name` is what the user will see in the verification message, e. g. `"Your verification code for Guest is: CODE"` `seconds` is how many seconds the code is valid. Default is 10 minutes. Maximum is one day. Both functions can also be used by supplying the callback or by awaiting them (see [Sending an SMS](#sending-an-sms)). Here are the example result objects of the `sendVerificationSMS` function: ```javascript // Example result of a successfully sent verification code { ok: true, // true if and only if the code was successfully sent status: 200, message: 'Verification SMS sent. ', data: { verification_code: '445180', expires: 1676901632181, message_text: 'Your verification code for My super cool app is:\n445180' } } // Example result of an unsuccessfully sent verification code { ok: false, status: 400, message: 'Invalid API key or user id.' //This can be different for other errors } ``` And here are the example result objects of the `verifyCode` function: ```javascript // Example result of a verified code { ok: true, valid: true, // true if and only if the phone number is verified status: 200, message: 'The code is valid. ', valid_code: '445180', expires: 1676901632181 } // Failed to verify the code { ok: true, valid: false status: 400, message: 'The code is invalid. ' //This can be different for other errors } // Another error { ok: false, valid: false, status: 401, message: 'Invalid API key or user id.' //This can be different for other errors } ``` ## Sending bulk SMS TextFlow Node.js helper library still does not include the bulk SMS functionality, but you can use the libraries like axios to make the REST API calls. ```bash npm install axios ``` Check our [REST API documentation](/rest-api.md#sending-bulk-sms) for the full description of endpoints and possible server responses. ```javascript const axios = require('axios'); const phone_numbers = ["+11234567890", "+11234567891", "11234567892"]; const text = "Dummy message text"; // Sending the bulk SMS axios.post("https://textflow.me/api/bulk-sms", { phone_numbers, text }, { headers: { "Authorization": "Bearer YOUR_API_KEY" } }) .then(resp => { // Response data is stored in resp.data }) .catch(err => { // This is executed when response code is different than 200 // Error data is stored in err.response.data }); // Checking the remaining SMS to send axios.post("https://textflow.me/api/bulk-count", {}, { headers: { "Authorization": "Bearer YOUR_API_KEY" } }) .then(resp => { console.log(resp.data) // Response data is stored in resp.data }) .catch(err => { // This is executed when response code is different than 200 console.log(err.response.data) // Error data is stored in err.response.data }); ``` ## Getting help If you need help installing or using the library, please check the [FAQ](https://textflow.me/api) first, and contact us at [support@textflow.me](mailto://support@textflow.me) if you don't find an answer to your question. If you've found a bug in the API, package or would like new features added, you are also free to contact us! --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.textflow.me/node.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.