// Telerivet Cloud Script API TypeScript Declarations // Documentation: https://telerivet.com/api/script // // ENTRY POINT: // Cloud Script services must define a main() function as the entry point. // The runtime automatically calls main() when the service is triggered. // // Example: // function main() { // project.sendMessage({ to_number: '+15554567890', content: 'Hello!' }); // return 'Message sent'; // } // // Context variables (like 'project', 'contact', 'message', etc.) are available // as globals depending on the service type. Return a value from main() or set // the 'return_value' global variable to return data from the script. // // However, when defining a custom action with type "run_script", // the code should not be within a main() function, e.g.: // // { // "type": "run_script", // "code": "project.sendMessage({ to_number: '+15554567890', content: 'Hello!' });" // } // // =========================================== // CODE EXAMPLES // =========================================== // // The following examples demonstrate common patterns for Cloud Script services. // For more examples, see https://telerivet.com/api/script#examples // // --- EXAMPLE: Keyword-based auto-reply --- // Service type: incoming_message_script // Responds to messages based on keywords like "join" or "stop" // // function main() { // let keyword = (word1 || "").toLowerCase(); // // if (keyword == 'join') { // let subscribers = project.getOrCreateGroup("Subscribers"); // contact.addToGroup(subscribers); // sendReply("Thanks for subscribing!"); // } else if (keyword == 'stop') { // let subscribers = project.getOrCreateGroup("Subscribers"); // contact.removeFromGroup(subscribers); // sendReply("Goodbye!"); // } else { // sendReply("Invalid keyword '" + keyword + "'."); // } // } // // --- EXAMPLE: Query contacts from your database --- // Service type: incoming_message_script // Searches for contacts whose name starts with the message content // // function main() { // var query = project.queryContacts({ // name: {prefix: content}, // sort: 'name' // }); // // var contacts = query.limit(5).all(); // // if (contacts.length) { // var contactsInfo = contacts.map(function(c) { // return c.name + " " + c.phone_number; // }).join("\n"); // sendReply(contactsInfo); // } else { // sendReply("No contacts found starting with '" + content + "'."); // } // } // // --- EXAMPLE: Store data in a data table --- // Service type: incoming_message_script // Parses structured SMS data and saves it to a data table // // function main() { // var parts = content.split(/#/g); // // if (parts.length != 3) { // sendReply("Invalid format. Please use: field1#field2#field3"); // return; // } // // var table = project.getOrCreateDataTable("Reports"); // var row = table.createRow({ // contact_id: contact.id, // from_number: from_number, // vars: { // field1: parts[0], // field2: parts[1], // field3: parts[2] // } // }); // // sendReply("Your report has been recorded!"); // } // // --- EXAMPLE: Multi-step conversation flow --- // Service type: incoming_message_script // Implements a registration flow that collects name and email // // function main() { // var keyword = (word1 || "").toLowerCase(); // if (keyword == 'join') { // sendReply("What is your name?"); // waitForResponse('name', { // timeoutMinutes: 10, // timeoutId: 'name_reminder' // }); // } // } // // addResponseHandler('name', function() { // contact.name = content; // sendReply("Hi, " + contact.name + ". What is your email address?"); // waitForResponse('email', { // timeoutMinutes: 10, // timeoutId: 'email_reminder' // }); // }); // // addResponseHandler('email', function() { // contact.vars.email = content; // var usersGroup = project.getOrCreateGroup("Registered Users"); // contact.addToGroup(usersGroup); // sendReply("Thanks! You are now registered."); // }); // // addTimeoutHandler('name_reminder', function() { // sendReply("Please send your name to complete registration."); // waitForResponse('name', { timeoutDays: 1 }); // }); // // --- EXAMPLE: Call external JSON API --- // Service type: incoming_message_script // Makes an HTTP request to an external API and parses the response // // function main() { // var url = "https://api.example.com/data"; // // var response = httpClient.request(url, { // method: 'GET', // headers: { 'Accept': 'application/json' } // }); // // var data = JSON.parse(response.content); // sendReply("Result: " + data.value); // } // // --- EXAMPLE: USSD menu with PIN protection --- // Service type: ussd_script // Implements an interactive USSD menu protected by a PIN // // function main() { // sendReply("Welcome! Please enter your PIN."); // promptDigits('pin'); // } // // addInputHandler('pin', function(input) { // var correctPin = contact.vars.pin || '1234'; // if (input == correctPin) { // sendReply("1 - show balance\n2 - change PIN"); // promptDigits('menu_option'); // } else { // sendReply("Incorrect PIN."); // } // }); // // addInputHandler('menu_option', function(input) { // if (input == '1') { // var balance = contact.vars.balance || 0; // sendReply("Your balance is " + balance + "."); // } else if (input == '2') { // sendReply("Please enter a new 4-digit PIN."); // promptDigits('new_pin'); // } // }); // // addInputHandler('new_pin', function(input) { // if (input.length == 4) { // contact.vars.pin = input; // sendReply("Your PIN has been updated."); // } else { // sendReply("Invalid PIN length."); // } // }); // // --- EXAMPLE: Store custom data on contact --- // Any script context with contact variable // Saves custom fields to the contact // // function main() {} // contact.vars.custom_field = 'value'; // contact.save(); // } // // --- EXAMPLE: Add/remove contact from group --- // Any script context with contact variable // // function main() { // var group = project.getOrCreateGroup('my_group'); // contact.addToGroup(group); // // or: contact.removeFromGroup(group); // } // // =========================== // JavaScript Language Support // =========================== // // Some ES2015 language features are not currently available in Telerivet's script engine, including: // - import, export, and class keywords // - spread operator (... in function calls) // - const keyword within loops // JavaScript code should avoid using these language features to avoid errors. // /** * Cursor for iterating over query results. * @template T The type of items in the cursor */ declare interface Cursor { /** * Returns true if there are more results to iterate. */ hasNext(): boolean; /** * Returns the next result. */ next(): T; /** * Limits the number of results returned. * @param count Maximum number of results */ limit(count: number): Cursor; /** * Returns the total count of items matching the query. */ count(): number; /** * Returns all items matching the query as an array. * Warning: This may result in many API calls for large result sets. */ all(): T[]; } /** * Base class for Telerivet entities. * Most API objects (Message, Contact, Project, etc.) extend this class. */ declare class Entity { /** Unique identifier for this entity */ readonly id: string; } /** * Represents a single message. */ declare class Message extends Entity { /** ID of the message */ readonly id: string; /** Direction of the message: incoming messages are sent from one of your contacts to your phone; outgoing messages are sent from your phone to one of your contacts */ readonly direction: "incoming" | "outgoing"; /** Current status of the message */ readonly status: "ignored" | "processing" | "received" | "sent" | "queued" | "failed" | "failed_queued" | "cancelled" | "delivered" | "not_delivered" | "read"; /** Type of the message */ readonly message_type: "sms" | "mms" | "ussd" | "ussd_session" | "call" | "chat" | "service"; /** How the message originated within Telerivet */ readonly source: "phone" | "provider" | "web" | "api" | "service" | "webhook" | "scheduled" | "integration"; /** The time that the message was created on Telerivet's servers */ readonly time_created: number; /** The time that the message was reported to have been sent (null for incoming messages and messages that have not yet been sent) */ readonly time_sent: number | null; /** The time that the message was last updated in Telerivet. */ readonly time_updated: number; /** The phone number that the message originated from (your number for outgoing messages, the contact's number for incoming messages) */ readonly from_number: string; /** The phone number that the message was sent to (your number for incoming messages, the contact's number for outgoing messages) */ readonly to_number: string; /** The text content of the message (null for USSD messages and calls) */ readonly content: string; /** Whether this message is starred in Telerivet */ starred: boolean; /** Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone) */ readonly simulated: boolean; /** List of IDs of labels applied to this message */ readonly label_ids: string[]; /** Route-specific parameters for the message. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters. */ readonly route_params: object | null; /** Custom variables stored for this message. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. */ vars: object; /** Priority of this message. Telerivet will attempt to send messages with higher priority numbers first. Only defined for outgoing messages. */ readonly priority: number; /** The number of times Telerivet has attempted to send the message. Will be greater than 1 if the message has been resent. Only defined for outgoing messages. */ readonly send_attempts: number | null; /** A description of the error encountered while sending a message. (This field is omitted from the API response if there is no error message.) */ error_message: string; /** A route-specific error code encountered while sending a message. The error code values depend on the provider and may be described in the provider's API documentation. Error codes may be strings or numbers, depending on the provider. (This field is omitted from the API response if there is no error code.) */ readonly error_code: string; /** The ID of this message from an external SMS gateway provider (e.g. Twilio or Vonage), if available. */ readonly external_id: string; /** The number of SMS parts associated with the message, if applicable and if known. */ readonly num_parts: number | null; /** The price of this message, if known. */ readonly price: number | null; /** The currency of the message price, if applicable. */ readonly price_currency: string; /** The duration of the call in seconds, if known, or -1 if the call was not answered. */ readonly duration: number | null; /** The length of time the call rang in seconds before being answered or hung up, if known. */ readonly ring_time: number | null; /** For voice calls, the URL of an MP3 file to play when the contact answers the call */ readonly audio_url: string; /** For voice calls, the language of the text-to-speech voice */ readonly tts_lang: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; /** For voice calls, the text-to-speech voice */ readonly tts_voice: "female" | "male"; /** If true, URLs in the message content are short URLs that redirect to a destination URL. */ readonly track_clicks: boolean; /** For text messages containing short URLs, this is an array of objects with the properties `short_url`, `link_type`, `time_clicked` (the first time that URL was clicked), and `expiration_time`. If `link_type` is "redirect", the object also contains a `destination_url` property. If `link_type` is "media", the object also contains an `media_index` property (the index in the media array). If `link_type` is "service", the object also contains a `service_id` property. This property is undefined for messages that do not contain short URLs. */ readonly short_urls: any[]; /** A string identifying the network that sent or received the message, if known. For mobile networks, this string contains the 3-digit mobile country code (MCC) followed by the 2- or 3-digit mobile network code (MNC), which results in a 5- or 6-digit number. For lists of mobile network operators and their corresponding MCC/MNC values, see Mobile country code Wikipedia article. The network_code property may be non-numeric for messages not sent via mobile networks. */ readonly network_code: string; /** For text messages containing media files, this is an array of objects with the properties `url`, `type` (MIME type), `filename`, and `size` (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day. */ readonly media: any[]; /** A list of parts in the MMS message (only for incoming MMS messages received via Telerivet Gateway Android app). Each MMS part in the list is an object with the following properties: - cid: MMS content-id - type: MIME type - filename: original filename - size (int): number of bytes - url: URL where the content for this part is stored (secret but publicly accessible, so you could link/embed it in a web page without having to re-host it yourself) In general, the `media` property of the message is recommended for retrieving information about MMS media files, instead of `mms_parts`. The `mms_parts` property is also only present when retrieving an individual MMS message by ID, not when querying a list of messages. */ readonly mms_parts: any[]; /** If the message contains any short URLs, this is the first time that a short URL in the message was clicked. This property is undefined for messages that do not contain short URLs. */ readonly time_clicked: number; /** ID of the service that handled the message (for voice calls, the service defines the call flow) */ readonly service_id: string; /** ID of the phone (basic route) that sent or received the message */ readonly phone_id: string; /** ID of the contact that sent or received the message */ readonly contact_id: string; /** ID of the custom route that sent the message (if applicable) */ readonly route_id: string; /** ID of the broadcast that this message is part of (if applicable) */ readonly broadcast_id: string; /** ID of the scheduled message that created this message is part of (if applicable) */ readonly scheduled_id: string; /** ID of the Telerivet user who sent the message (if applicable) */ readonly user_id: string; /** ID of the project this contact belongs to */ readonly project_id: string; /** URL to this message in the Telerivet web app */ readonly url: string; /** * Returns true if this message has a particular label, false otherwise. */ hasLabel(label: Label): boolean; /** * Adds a label to the given message. */ addLabel(label: Label): void; /** * Removes a label from the given message. */ removeLabel(label: Label): void; /** * Saves any fields that have changed for this message. */ save(): void; /** * Resends a message, for example if the message failed to send or if it * was not delivered. If the message was originally in the queued, * retrying, failed, or cancelled states, then Telerivet will return the * same message object. Otherwise, Telerivet will create and return a new * message object. */ resend(options?: { route_id?: string }): Message; /** * Cancels sending a message that has not yet been sent. Returns the * updated message object. Only valid for outgoing messages that are * currently in the queued, retrying, or cancelled states. For other * messages, the API will return an error with the code 'not_cancellable'. */ cancel(): Message; /** * Deletes this message. */ delete(): void; } /** * Represents a scheduled message within Telerivet. */ declare class ScheduledMessage extends Entity { /** ID of the scheduled message */ readonly id: string; /** Text content of the scheduled message */ content: string; /** Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see RFC2445. */ rrule: string; /** Timezone ID used to compute times for recurring messages; see List of tz database time zones Wikipedia article. */ timezone_id: string; /** List of recipients. Each recipient is an object with a string `type` property, which may be `"phone_number"`, `"group"`, or `"filter"`. If the type is `"phone_number"`, the `phone_number` property will be set to the recipient's phone number. If the type is `"group"`, the `group_id` property will be set to the ID of the group, and the `group_name` property will be set to the name of the group. If the type is `"filter"`, the `filter_type` property (string) and `filter_params` property (object) describe the filter used to send the broadcast. (API clients should not rely on a particular value or format of the `filter_type` or `filter_params` properties, as they may change without notice.) */ readonly recipients: object[]; /** A string with a human readable description of the first few recipients (possibly truncated) */ readonly recipients_str: string; /** ID of the group to send the message to (null if the recipient is an individual contact, or if there are multiple recipients) */ group_id: string; /** ID of the contact to send the message to (null if the recipient is a group, or if there are multiple recipients) */ contact_id: string; /** Phone number to send the message to (null if the recipient is a group, or if there are multiple recipients) */ to_number: string; /** ID of the phone or route the message will be sent from */ route_id: string; /** The service associated with this message (for voice calls, the service defines the call flow) */ service_id: string; /** For voice calls, the URL of an MP3 file to play when the contact answers the call */ audio_url: string; /** For voice calls, the language of the text-to-speech voice */ tts_lang: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; /** For voice calls, the text-to-speech voice */ tts_voice: "female" | "male"; /** Type of scheduled message */ readonly message_type: "sms" | "mms" | "ussd" | "ussd_session" | "call" | "chat" | "service"; /** Time the scheduled message was created in Telerivet */ readonly time_created: number; /** The time that the message will be sent (or first sent for recurring messages) */ start_time: number; /** Time after which a recurring message will stop (not applicable to non-recurring scheduled messages) */ end_time: number | null; /** The most recent time that Telerivet has sent this scheduled message (null if it has never been sent) */ readonly prev_time: number | null; /** The next upcoming time that Telerivet will sent this scheduled message (null if it will not be sent again) */ readonly next_time: number | null; /** Number of times this scheduled message has already been sent */ readonly occurrences: number; /** Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise */ replace_variables: boolean; /** If true, URLs in the message content will automatically be replaced with unique short URLs */ track_clicks: boolean; /** For text messages containing media files, this is an array of objects with the properties `url`, `type` (MIME type), `filename`, and `size` (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day. */ readonly media: any[]; /** Route-specific parameters to use when sending the message. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters. */ route_params: object | null; /** Custom variables stored for this scheduled message (copied to Message when sent). Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. */ vars: object; /** IDs of labels to add to the Message */ label_ids: string[]; /** ID of the relative scheduled message this scheduled message was created from, if applicable */ readonly relative_scheduled_id: string; /** ID of the project this scheduled message belongs to */ readonly project_id: string; /** Set to true if Telerivet will render variables like [[contact.name]] in the message content */ readonly is_template: boolean; /** * Saves any fields or custom variables that have changed for this * scheduled message. */ save(): void; /** * Cancels this scheduled message. */ delete(): void; } /** * A relative scheduled message is a message that is scheduled relative to a * date stored as a custom field for each recipient contact. This allows * scheduling messages on a different date for each contact, for example on * their birthday, a certain number of days before an appointment, or a certain * number of days after enrolling in a campaign. Telerivet will automatically * create a ScheduledMessage for each contact matching a * RelativeScheduledMessage. Any service that can be manually triggered for a * contact (including polls) may also be scheduled via a relative scheduled * message, whether or not the service actually sends a message. */ declare class RelativeScheduledMessage extends Entity { /** ID of the relative scheduled message */ readonly id: string; /** Text content of the relative scheduled message */ content: string; /** Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23) */ time_of_day: string; /** Custom contact variable storing date or date/time values relative to which messages will be scheduled. */ date_variable: string; /** The type of interval (day/week/month/year) that will be used to adjust the scheduled date relative to the date stored in the contact's date_variable, when offset_count is non-zero (D=day, W=week, M=month, Y=year) */ offset_scale: "D" | "W" | "M" | "Y"; /** The number of days/weeks/months/years to adjust the date of the scheduled message relative relative to the date stored in the contact's date_variable. May be positive, negative, or zero. */ offset_count: number; /** Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see RFC2445. */ rrule: string; /** Time after which recurring messages will stop (not applicable to non-recurring scheduled messages) */ end_time: number | null; /** Timezone ID used to compute times for recurring messages; see List of tz database time zones Wikipedia article. */ timezone_id: string; /** A string with a human readable description of the recipient */ readonly recipients_str: string; /** ID of the group to send the message to (null if the recipient is an individual contact) */ group_id: string; /** ID of the contact to send the message to (null if the recipient is a group) */ contact_id: string; /** Phone number to send the message to (null if the recipient is a group) */ to_number: string; /** ID of the phone or route the message will be sent from */ route_id: string; /** The service associated with this message (for voice calls, the service defines the call flow) */ service_id: string; /** For voice calls, the URL of an MP3 file to play when the contact answers the call */ audio_url: string; /** For voice calls, the language of the text-to-speech voice */ tts_lang: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; /** For voice calls, the text-to-speech voice */ tts_voice: "female" | "male"; /** Type of scheduled message */ readonly message_type: "sms" | "mms" | "ussd" | "ussd_session" | "call" | "chat" | "service"; /** Time the relative scheduled message was created in Telerivet */ readonly time_created: number; /** Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise */ replace_variables: boolean; /** If true, URLs in the message content will automatically be replaced with unique short URLs */ track_clicks: boolean; /** For text messages containing media files, this is an array of objects with the properties `url`, `type` (MIME type), `filename`, and `size` (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day. */ readonly media: any[]; /** Route-specific parameters to use when sending the message. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters. */ route_params: object | null; /** Custom variables stored for this scheduled message (copied to each ScheduledMessage and Message when sent). Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. */ vars: object; /** IDs of labels to add to the Message */ label_ids: string[]; /** ID of the project this relative scheduled message belongs to */ readonly project_id: string; /** * Saves any fields or custom variables that have changed for this relative * scheduled message. */ save(): void; /** * Deletes this relative scheduled message and any associated scheduled * messages. */ delete(): void; } declare class Contact extends Entity { /** ID of the contact */ readonly id: string; /** Name of the contact */ name: string; /** Phone number of the contact */ phone_number: string; /** Time the contact was added in Telerivet */ readonly time_created: number; /** Time the contact was last updated in Telerivet */ readonly time_updated: number; /** True if Telerivet is blocked from sending messages to this contact */ send_blocked: boolean; /** Current status of the conversation with this contact */ conversation_status: "closed" | "active" | "handled"; /** Last time the contact sent or received a message (null if no messages have been sent or received) */ readonly last_message_time: number | null; /** Last time a message was received from this contact */ readonly last_incoming_message_time: number | null; /** Last time a message was sent to this contact */ readonly last_outgoing_message_time: number | null; /** Total number of non-deleted messages sent to or received from this contact */ readonly message_count: number; /** Number of messages received from this contact */ readonly incoming_message_count: number; /** Number of messages sent to this contact */ readonly outgoing_message_count: number; /** ID of the last message sent to or received from this contact (null if no messages have been sent or received) */ readonly last_message_id: string; /** ID of the basic route (phone) or custom route that Telerivet will use by default to send messages to this contact (null if using project default route) */ default_route_id: string; /** List of IDs of groups that this contact belongs to */ readonly group_ids: string[]; /** Custom variables stored for this contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. */ vars: object; /** ID of the project this contact belongs to */ readonly project_id: string; /** URL to this contact in the Telerivet web app */ readonly url: string; /** * Queries messages sent or received by this contact. */ queryMessages(options?: { direction?: "incoming" | "outgoing"; message_type?: "sms" | "mms" | "ussd" | "ussd_session" | "call" | "chat" | "service"; source?: "phone" | "provider" | "web" | "api" | "service" | "webhook" | "scheduled" | "integration"; starred?: boolean; status?: "ignored" | "processing" | "received" | "sent" | "queued" | "failed" | "failed_queued" | "cancelled" | "delivered" | "not_delivered" | "read"; "time_created[min]"?: number; "time_created[max]"?: number; external_id?: string; contact_id?: string; phone_id?: string; broadcast_id?: string; scheduled_id?: string; group_id?: string; sort?: "default"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Queries groups for which this contact is a member. */ queryGroups(options?: { name?: string; dynamic?: boolean; sort?: "default" | "name"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Queries messages scheduled to this contact (not including messages * scheduled to groups that this contact is a member of) */ queryScheduledMessages(options?: { message_type?: "sms" | "mms" | "ussd" | "ussd_session" | "call" | "chat" | "service"; time_created?: number; next_time?: number; relative_scheduled_id?: string; sort?: "default" | "next_time"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Queries data rows associated with this contact (in any data table). */ queryDataRows(options?: { time_created?: number; sort?: "default"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Queries this contact's current states for any service */ queryServiceStates(options?: { id?: string; vars?: object; sort?: "default"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Returns true if this contact is in a particular group, false otherwise. */ isInGroup(group: Group): boolean; /** * Adds this contact to a group. */ addToGroup(group: Group): void; /** * Removes this contact from a group. */ removeFromGroup(group: Group): void; /** * Saves any fields or custom variables that have changed for this contact. */ save(): void; /** * Deletes this contact. */ delete(): void; } /** * Represents a collection of related outgoing messages. Typically, messages in * a broadcast have the same content template and were sent at the same time; * however, a broadcast can also contain messages with unrelated content and * messages that were sent at different times. A broadcast is automatically * created when sending a message to a group of contacts. */ declare class Broadcast extends Entity { /** ID of the broadcast */ readonly id: string; /** List of recipients. Each recipient is an object with a string `type` property, which may be `"phone_number"`, `"group"`, or `"filter"`. If the type is `"phone_number"`, the `phone_number` property will be set to the recipient's phone number. If the type is `"group"`, the `group_id` property will be set to the ID of the group, and the `group_name` property will be set to the name of the group. If the type is `"filter"`, the `filter_type` property (string) and `filter_params` property (object) describe the filter used to send the broadcast. (API clients should not rely on a particular value or format of the `filter_type` or `filter_params` properties, as they may change without notice.) */ readonly recipients: object[]; /** Title of the broadcast. If a title was not provided when the broadcast was sent, it is automatically set to a human readable description of the first few recipients (possibly truncated) */ readonly title: string; /** Time the broadcast was sent in Telerivet */ readonly time_created: number; /** Time the most recent message was queued to send in this broadcast */ readonly last_message_time: number | null; /** Time the most recent message was sent (or failed to send) in this broadcast, or null if no messages have been sent yet */ readonly last_send_time: number | null; /** An object whose keys are the possible status codes (`"queued"`, `"sent"`, `"failed"`, `"failed_queued"`, `"delivered"`, `"not_delivered"`, and `"cancelled"`), and whose values are the number of messages in the broadcast currently in that status. */ readonly status_counts: object; /** The total number of messages created for this broadcast. For large broadcasts, the messages may not be created immediately after the broadcast is sent. The `message_count` includes messages in any status, including messages that are still queued. */ readonly message_count: number; /** The estimated number of messages in this broadcast when it is complete. The `estimated_count` is calculated at the time the broadcast is sent. When the broadcast is completed, the `estimated_count` may differ from `message_count` if there are any blocked contacts among the recipients (blocked contacts are included in `estimated_count` but not in `message_count`), if any contacts don't have phone numbers, or if the group membership changed while the broadcast was being sent. */ readonly estimated_count: number; /** The total number of SMS parts that have been sent in this broadcast. The number of SMS parts does not include messages that are still queued, or messages that failed to send. */ readonly num_parts: number | null; /** Type of message sent from this broadcast */ readonly message_type: "sms" | "mms" | "ussd" | "ussd_session" | "call" | "chat" | "service"; /** The text content of the message (null for USSD messages and calls) */ readonly content: string; /** For voice calls, the URL of an MP3 file to play when the contact answers the call */ readonly audio_url: string; /** For voice calls, the language of the text-to-speech voice */ readonly tts_lang: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; /** For voice calls, the text-to-speech voice */ readonly tts_voice: "female" | "male"; /** Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise */ readonly replace_variables: boolean; /** The current status of the broadcast. */ readonly status: "queuing" | "sending" | "complete" | "cancelled"; /** How the message originated within Telerivet */ readonly source: "phone" | "provider" | "web" | "api" | "service" | "webhook" | "scheduled" | "integration"; /** Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone) */ readonly simulated: boolean; /** If true, URLs in the message content will automatically be replaced with unique short URLs. */ readonly track_clicks: boolean; /** The number of messages in this broadcast containing short links that were clicked. At most one click per message is counted. If track_clicks is false, this property will be null. */ readonly clicked_count: number | null; /** List of IDs of labels applied to all messages in the broadcast */ readonly label_ids: string[]; /** For text messages containing media files, this is an array of objects with the properties `url`, `type` (MIME type), `filename`, and `size` (file size in bytes). Unknown properties are null. This property is undefined for messages that do not contain media files. Note: For files uploaded via the Telerivet web app, the URL is temporary and may not be valid for more than 1 day. */ readonly media: any[]; /** Custom variables stored for this broadcast. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. */ readonly vars: object; /** Route-specific parameters for the messages in the broadcast. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters. */ readonly route_params: object | null; /** The total price of all messages in this broadcast, if known. */ readonly price: number | null; /** The currency of the message price, if applicable. */ readonly price_currency: string; /** The number of replies received in response to a message sent in this broadcast. (Replies are not included in `message_count` ,`status_counts`, or `price`.) */ readonly reply_count: number; /** Time the most recent reply was received in response to a message sent in this broadcast, or null if no replies have been sent yet */ readonly last_reply_time: number | null; /** ID of the phone or route used to send the broadcast (if applicable) */ readonly route_id: string; /** The service associated with this broadcast (for voice calls, the service defines the call flow) */ readonly service_id: string; /** ID of the Telerivet user who sent the broadcast (if applicable) */ readonly user_id: string; /** ID of the project this broadcast belongs to */ readonly project_id: string; /** Set to true if Telerivet will render variables like [[contact.name]] in the message content */ readonly is_template: boolean; /** A string with a human readable description of the first few recipients (possibly truncated) */ readonly recipients_str: string; /** * Cancels sending a broadcast that has not yet been completely sent. No * additional messages will be queued, and any existing queued messages * will be cancelled when they would otherwise have been sent (except for * messages already queued on the Telerivet Android app, which will not be * automatically cancelled). */ cancel(): Broadcast; } /** * Represents an asynchronous task that is applied to all entities matching a * filter. Tasks include services applied to contacts, messages, or data rows; * adding or removing contacts from a group; blocking or unblocking sending * messages to a contact; updating a custom variable; deleting contacts, * messages, or data rows; or exporting data to CSV. */ declare class Task extends Entity { /** ID of the task */ readonly id: string; /** The task type */ readonly task_type: string; /** Parameters applied to all matching rows (specific to `task_type`). See project.createTask. */ readonly task_params: object; /** Type of filter defining the rows that the task is applied to */ readonly filter_type: string; /** Parameters defining the rows that the task is applied to (specific to `filter_type`). See project.createTask. */ readonly filter_params: object; /** Time the task was created in Telerivet */ readonly time_created: number; /** Time Telerivet started executing the task */ readonly time_active: number | null; /** Time Telerivet finished executing the task */ readonly time_complete: number | null; /** The total number of rows matching the filter (null if not known) */ readonly total_rows: number | null; /** The number of rows that have been processed so far */ readonly current_row: number | null; /** The current status of the task */ readonly status: "created" | "queued" | "active" | "complete" | "failed" | "cancelled"; /** Error message if the task failed */ readonly error_message: string | null; /** Custom variables stored for this task. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. */ readonly vars: object; /** ID of the data table this task is applied to (if applicable) */ readonly table_id: string; /** ID of the Telerivet user who created the task (if applicable) */ readonly user_id: string; /** ID of the project this task belongs to */ readonly project_id: string; /** * Cancels a task that is not yet complete. */ cancel(): Task; } /** * Represents a Telerivet project. Provides methods for sending and scheduling * messages, as well as accessing, creating and updating a variety of entities, * including contacts, messages, scheduled messages, groups, labels, phones, * services, and data tables. */ declare class Project extends Entity { /** ID of the project */ readonly id: string; /** Name of the project */ name: string; /** Default TZ database timezone ID; see List of tz database time zones Wikipedia article. */ timezone_id: string; /** Unique string used as a component of the project's URL in the Telerivet web app */ url_slug: string; /** The ID of a basic route or custom route that will be used to send messages by default (via both the API and web app), unless a particular route ID is specified when sending the message. */ default_route_id: string; /** If true, a contact will be automatically created for each unique phone number that a message is sent to or received from. If false, contacts will not automatically be created (unless contact information is modified by an automated service). The Conversations tab in the web app will only show messages that are associated with a contact. */ auto_create_contacts: boolean; /** Custom variables stored for this project. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable. */ vars: object; /** ID of the organization this project belongs to */ readonly organization_id: string; /** URL to this project in the Telerivet web app */ readonly url: string; /** * Sends one message (SMS, MMS, chat app message, voice call, or USSD * request). */ sendMessage(options: { message_type?: "text" | "sms" | "mms" | "ussd" | "call" | "chat" | "service"; content: string; to_number: string; contact_id: string; route_id?: string; status_url?: string; status_secret?: string; replace_variables?: boolean; track_clicks?: boolean; short_link_params?: object; media_urls?: string[]; route_params?: object; label_ids?: string[]; vars?: object; priority?: "1" | "2"; simulated?: boolean; service_id?: string; audio_url?: string; tts_lang?: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; tts_voice?: "female" | "male" }): Message; /** * Sends a text message (optionally with mail-merge templates) or voice * call to a group or a list of up to 500 phone numbers. With * `message_type`=`service`, invokes an automated service (such as a poll) * for a group or list of phone numbers. Any service that can be triggered * for a contact can be invoked via this method, whether or not the service * actually sends a message. */ sendBroadcast(options: { message_type?: "text" | "sms" | "mms" | "call" | "chat" | "service"; content: string; group_id: string; to_numbers: string[]; route_id?: string; title?: string; status_url?: string; status_secret?: string; label_ids?: string[]; exclude_contact_id?: string; replace_variables?: boolean; track_clicks?: boolean; short_link_params?: object; media_urls?: string[]; vars?: object; route_params?: object; service_id: string; audio_url?: string; tts_lang?: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; tts_voice?: "female" | "male" }): Broadcast; /** * Sends up to 100 different messages in a single API request. This method * is significantly faster than sending a separate API request for each * message. */ sendMulti(options: { messages: any[]; message_type?: "text" | "sms" | "mms" | "call" | "chat" | "service"; route_id?: string; broadcast_id?: string; broadcast_title?: string; status_url?: string; status_secret?: string; label_ids?: string[]; replace_variables?: boolean; track_clicks?: boolean; short_link_params?: object; media_urls?: string[]; route_params?: object; vars?: object; priority?: "1" | "2"; simulated?: boolean }): { 0: string; 1: string }; /** * Schedules a message to a group or single contact. Note that Telerivet * only sends scheduled messages approximately once every 15 seconds, so it * is not possible to control the exact second at which a scheduled message * is sent. Only one of the parameters group_id, to_number, and contact_id * should be provided. With `message_type`=`service`, schedules an * automated service (such as a poll) to be invoked for a group or list of * phone numbers. Any service that can be triggered for a contact can be * scheduled via this method, whether or not the service actually sends a * message. */ scheduleMessage(options: { message_type?: "text" | "sms" | "mms" | "ussd" | "call" | "chat" | "service"; content: string; group_id?: string; to_number?: string; contact_id?: string; start_time: number; start_time_offset: number; rrule?: string; route_id?: string; service_id: string; audio_url?: string; tts_lang?: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; tts_voice?: "female" | "male"; track_clicks?: boolean; short_link_params?: object; replace_variables?: boolean; media_urls?: string[]; route_params?: object; label_ids?: string[]; timezone_id?: string; end_time?: number; end_time_offset?: number; vars?: object }): ScheduledMessage; /** * Creates a relative scheduled message. This allows scheduling messages on * a different date for each contact, for example on their birthday, a * certain number of days before an appointment, or a certain number of * days after enrolling in a campaign. Telerivet will automatically create * a ScheduledMessage for each contact matching a RelativeScheduledMessage. * Relative scheduled messages can be created for a group or an individual * contact, although dynamic groups are not supported. Only one of the * parameters group_id, to_number, and contact_id should be provided. With * message_type=service, schedules an automated service (such as a poll). * Any service that can be triggered for a contact can be scheduled via * this method, whether or not the service actually sends a message. */ createRelativeScheduledMessage(options: { message_type?: "text" | "sms" | "mms" | "call" | "chat" | "service"; content: string; group_id?: string; to_number?: string; contact_id?: string; time_of_day: string; timezone_id?: string; date_variable: string; offset_scale?: "D" | "W" | "M" | "Y"; offset_count?: number; rrule?: string; route_id?: string; service_id: string; audio_url?: string; tts_lang?: "en-US" | "en-GB" | "en-GB-WLS" | "en-AU" | "en-IN" | "da-DK" | "nl-NL" | "fr-FR" | "fr-CA" | "de-DE" | "is-IS" | "it-IT" | "pl-PL" | "pt-BR" | "pt-PT" | "ru-RU" | "es-ES" | "es-US" | "sv-SE"; tts_voice?: "female" | "male"; track_clicks?: boolean; short_link_params?: object; replace_variables?: boolean; media_urls?: string[]; route_params?: object; label_ids?: string[]; end_time?: number; end_time_offset?: number; vars?: object }): RelativeScheduledMessage; /** * Add an incoming message to Telerivet. Acts the same as if the message * was received by a phone. Also triggers any automated services that apply * to the message. */ receiveMessage(options: { content: string; message_type?: "sms" | "call" | "chat"; from_number: string; phone_id: string; to_number?: string; simulated?: boolean; starred?: boolean; label_ids?: string[]; vars?: object }): Message; /** * Retrieves OR creates and possibly updates a contact by name or phone * number. If a phone number is provided, by default, Telerivet will search * for an existing contact with that phone number (including suffix matches * to allow finding contacts with phone numbers in a different format). If * a phone number is not provided but a name is provided, Telerivet will * search for a contact with that exact name (case insensitive). This * behavior can be modified by setting the `lookup_key` parameter to look * up a contact by another field, including a custom variable. If no * existing contact is found, a new contact will be created. Then that * contact will be updated with any parameters provided (`name`, * `phone_number`, `vars`, `default_route_id`, `send_blocked`, * `add_group_ids`, `remove_group_ids`). */ getOrCreateContact(options?: { name?: string; phone_number?: string; lookup_key?: "phone_number" | "name" | "id" | "vars.variable_name" | "none"; send_blocked?: boolean; default_route_id?: string; add_group_ids?: string[]; id?: string; remove_group_ids?: string[]; vars?: object }): Contact; /** * Creates and/or updates up to 200 contacts in a single API call. When * creating or updating a large number of contacts, this method is * significantly faster than sending a separate API request for each * contact. By default, if the phone number for any contact matches an * existing contact, the existing contact will be updated with any * information provided. This behavior can be modified by setting the * `lookup_key` parameter to look up contacts by another field, including a * custom variable. If any contact was not found matching the provided * `lookup_key`, a new contact will be created. */ importContacts(options: { contacts: any[]; lookup_key?: "phone_number" | "id" | "vars.variable_name" | "none"; add_group_ids?: string[]; remove_group_ids?: string[]; default_route_id?: string }): { 0: string }; /** * Queries contacts within the given project. */ queryContacts(options?: { group_id?: string; name?: string; phone_number?: string; time_created?: number; last_message_time?: number; last_incoming_message_time?: number; last_outgoing_message_time?: number; incoming_message_count?: number; outgoing_message_count?: number; send_blocked?: boolean; vars?: object; sort?: "default" | "name" | "phone_number" | "last_message_time"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Initializes the Telerivet contact with the given ID without making an * API request. * @param id ID of the contact */ initContactById(id: string): Contact; /** * Queries basic routes within the given project. */ queryPhones(options?: { name?: string; phone_number?: string; last_active_time?: number; sort?: "default" | "name" | "phone_number"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Initializes the basic route with the given ID without making an API * request. * @param id ID of the phone - see */ initPhoneById(id: string): Phone; /** * Queries messages within the given project. */ queryMessages(options?: { label_id?: string; direction?: "incoming" | "outgoing"; message_type?: "sms" | "mms" | "ussd" | "ussd_session" | "call" | "chat" | "service"; source?: "phone" | "provider" | "web" | "api" | "service" | "webhook" | "scheduled" | "integration"; starred?: boolean; status?: "ignored" | "processing" | "received" | "sent" | "queued" | "failed" | "failed_queued" | "cancelled" | "delivered" | "not_delivered" | "read"; "time_created[min]"?: number; "time_created[max]"?: number; external_id?: string; contact_id?: string; phone_id?: string; broadcast_id?: string; scheduled_id?: string; group_id?: string; sort?: "default"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Initializes the Telerivet message with the given ID without making an * API request. * @param id ID of the message */ initMessageById(id: string): Message; /** * Queries broadcasts within the given project. */ queryBroadcasts(options?: { "time_created[min]"?: number; "time_created[max]"?: number; "last_message_time[min]"?: number; "last_message_time[max]"?: number; sort?: "default" | "last_message_time"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Initializes the Telerivet broadcast with the given ID without making an * API request. * @param id ID of the broadcast */ initBroadcastById(id: string): Broadcast; /** * Creates and starts an asynchronous task that is applied to all entities * matching a filter (e.g. contacts, messages, or data rows). Tasks are * designed to efficiently process a large number of entities. When * processing a large number of entities, tasks are much faster than using * the API to query and loop over all objects matching a filter. Several * different types of tasks are supported, including applying services to * contacts, messages, or data rows; adding or removing contacts from a * group; blocking or unblocking sending messages to a contact; updating a * custom variable; deleting contacts, messages, or data rows; or exporting * data to CSV. When using a task to apply a Custom Actions or Cloud Script * API service (`apply_service_to_contacts`, `apply_service_to_rows`, or * `apply_service_to_messages`), the `task` variable will be available * within the service. The service can use custom variables on the task * object (e.g. `task.vars.example`), such as to store aggregate statistics * for the rows matching the filter. */ createTask(options: { task_type: string; task_params?: object; filter_type: "query_contacts" | "contact_ids" | "query_rows" | "row_ids" | "query_messages" | "message_ids"; filter_params: object; table_id?: string; vars?: object }): Task; /** * Queries batch tasks within the given project. */ queryTasks(options?: { sort?: "default"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Initializes the task with the given ID without making an API request. * @param id ID of the task */ initTaskById(id: string): Task; /** * Queries groups within the given project. */ queryGroups(options?: { name?: string; dynamic?: boolean; sort?: "default" | "name"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor; /** * Retrieves or creates a group by name. * @param name Name of the group */ getOrCreateGroup(name: string): Group; /** * Initializes the group with the given ID without making an API request. * @param id ID of the group */ initGroupById(id: string): Group; /** * Queries labels within the given project. */ queryLabels(options?: { name?: string; sort?: "default" | "name"; sort_dir?: "asc" | "desc"; page_size?: number; offset?: number }): Cursor