{ "openapi": "3.1.0", "info": { "title": "Telerivet API", "description": "Telerivet's REST API and Webhook API provide programmatic access to messaging, contacts, automation, and analytics features.\n\n## Authentication\nThe API supports two authentication methods:\n\n**API Key (Basic Auth):** Use HTTP Basic Auth with your API key as the username (password is ignored). Each API key is associated with an API client, which has certain permissions for a Telerivet project or organization. You can manage API clients and generate API keys on the [Developer API](https://telerivet.com/dashboard/api) settings page.\n\n**OAuth 2.0 (Bearer Token):** Send an `Authorization: Bearer {access_token}` header. OAuth tokens are scoped to specific permissions and can optionally be restricted to a single organization. Supports authorization code flow (with PKCE), device authorization flow (RFC 8628), and refresh tokens. The API supports CORS for OAuth 2.0 Bearer token requests, enabling browser-based JavaScript applications to call the API directly. CORS is not supported for API key authentication. See the [OAuth 2.0 Guide](https://telerivet.com/api/oauth) for details.\n\n## Common Workflows\n\nMost operations require a project_id parameter. You can find the project ID from `GET /v1/projects`, or from the Developer API settings page at https://telerivet.com/dashboard/api#api_ids. \n\n**Send a message:**\n- Send an individual message with `POST /v1/projects/{project_id}/messages/send`\n- Send multiple messages with `POST /v1/projects/{project_id}/send_multi` or `POST /v1/projects/{project_id}/send_broadcast`\n- Schedule a message with `POST /v1/projects/{project_id}/scheduled`\n\n**Look up a contact:**\n- Look up a contact by phone number with `GET /v1/projects/{project_id}/contacts?phone_number={number}`\n- Or get a contact by ID with `GET /v1/projects/{project_id}/contacts/{contact_id}`\n\n**Create/update contacts:**\n- Use `POST /v1/projects/{project_id}/contacts` to create/update a contact by phone number\n- Or use `POST /v1/projects/{project_id}/contacts/{contact_id}` to update a contact by ID\n- Or use `POST /v1/projects/{project_id}/import_contacts` to import or update multiple contacts at once\n\n**Configure automated services:**\n- Use `POST /v1/projects/{project_id}/services` to create an automated service\n- Use `POST /v1/projects/{project_id}/services/{service_id}/config` to update the configuration for an existing automated service\n\n## Resource Hierarchy\n- Organization (account) \u2192 Projects \u2192 Contacts, Messages, Groups, Services, etc.\n\n## Documentation\nFull documentation: https://telerivet.com/api/rest\n\n## Cloud Script API\nWhen creating Cloud Script services (`*_script` service types), your code can use the JavaScript API documented at https://api.telerivet.com/script.d.ts. This TypeScript declaration file describes all available classes, methods, service type contexts, and includes code examples.\n\n## OpenAPI Spec\nThis specification is available at `https://api.telerivet.com/openapi.json`", "version": "1.9.5", "contact": { "name": "Telerivet Support", "url": "https://telerivet.com/contact" }, "x-llm-instructions": "When using this API: 1) Always get project_id first if not provided. 2) Check response for 'error' field to detect failures. 3) For list endpoints, use 'page_size' parameter and check 'next_marker' for pagination. 4) For Custom Actions services, use x-action-types to find available action types and their schemas.", "x-service-types": { "incoming_message_actions": { "description": "Custom Actions service triggered when incoming messages are received.", "config": { "$ref": "#/components/schemas/ServiceConfigIncomingMessageActions" }, "example": { "service_type": "incoming_message_actions", "name": "My Custom Actions Service", "config": { "actions": [ { "type": "reply", "body": { "content": "Hello! Reply with your name." } }, { "type": "wait_response", "state_id": "waiting_name", "timeout": { "interval": "days", "days": 1, "subroutine": "name_timeout" } } ], "response_handlers": [ { "state_id": "waiting_name", "actions": [ { "type": "set_contact_name", "name": "[[content]]" }, { "type": "reply", "body": { "content": "Thanks, [[contact.name]]!" } } ] } ], "subroutines": [ { "name": "name_timeout", "actions": [ { "type": "log", "value": "Timeout while waiting for contact name." } ] } ] } } }, "contact_actions": { "description": "Custom Actions service that can be triggered for a contact.", "config": { "$ref": "#/components/schemas/ServiceConfigContactActions" }, "example": { "service_type": "contact_actions", "name": "Welcome New Contacts", "config": { "actions": [ { "type": "condition", "conditions": [ { "type": "is", "variable": "[[contact.vars.welcomed]]", "value": "" } ], "actions": [ { "type": "send_message", "body": { "content": "Welcome, [[contact.name]]! Reply HELP for assistance." } }, { "type": "set_variable", "variable": "contact.vars.welcomed", "value": "1" } ] } ] } } }, "message_actions": { "description": "Custom Actions service that can be triggered for a message.", "config": { "$ref": "#/components/schemas/ServiceConfigMessageActions" }, "example": { "service_type": "message_actions", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "project_actions": { "description": "Custom Actions service that can be manually triggered for a project.", "config": { "$ref": "#/components/schemas/ServiceConfigProjectActions" }, "example": { "service_type": "project_actions", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "message_status_actions": { "description": "Custom Actions service triggered when outgoing message statuses change.", "config": { "$ref": "#/components/schemas/ServiceConfigMessageStatusActions" }, "example": { "service_type": "message_status_actions", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "voice_actions": { "description": "Custom Actions service triggered for voice call events.", "config": { "$ref": "#/components/schemas/ServiceConfigVoiceActions" }, "example": { "service_type": "voice_actions", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "ussd_actions": { "description": "Custom Actions service triggered for USSD session events.", "config": { "$ref": "#/components/schemas/ServiceConfigUssdActions" }, "example": { "service_type": "ussd_actions", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "data_row_actions": { "description": "Custom Actions service that can be triggered for data table rows.", "config": { "$ref": "#/components/schemas/ServiceConfigDataRowActions" }, "example": { "service_type": "data_row_actions", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "incoming_message_webhook": { "description": "Webhook service that sends HTTP POST notifications when incoming messages are received. Use this to integrate with external systems that need to process incoming text messages or call notifications.", "config": { "$ref": "#/components/schemas/ServiceConfigIncomingMessageWebhook" }, "example": { "service_type": "incoming_message_webhook", "name": "My Webhook", "config": { "url": "https://example.com/webhook", "secret": "my_secret_123" } } }, "optin_optout": { "description": "Service that lets contacts opt-in and opt-out by sending keywords (e.g., JOIN, STOP). When a contact sends a matching keyword, the service can add or remove the contact from groups, apply labels, block or unblock the contact, and send an automated reply.", "config": { "$ref": "#/components/schemas/ServiceConfigOptinOptout" }, "example": { "service_type": "optin_optout", "name": "Newsletter Subscription", "config": { "subscribe_keywords": [ "JOIN", "START" ], "subscribe_reply": { "content": "You're subscribed! Reply STOP to unsubscribe." }, "unsubscribe_keywords": [ "STOP", "QUIT" ], "unsubscribe_reply": { "content": "You've been unsubscribed." }, "subscriber_group": "Newsletter Subscribers", "unsubscriber_group": "Newsletter Unsubscribers", "actions": { "add_subscriber": true, "remove_unsubscriber": true, "add_unsubscriber": true, "remove_subscriber": true, "add_subscribe_label": false, "add_unsubscribe_label": false, "subscribe_unblock": true, "unsubscribe_block": true } } } }, "keyword_auto_reply": { "description": "Service that matches incoming messages against one or more keywords and sends an auto-reply if the message content matches one of the keywords.", "config": { "$ref": "#/components/schemas/ServiceConfigKeywordAutoReply" }, "example": { "service_type": "keyword_auto_reply", "name": "Business Info", "config": { "items": [ { "keywords": [ "HOURS", "SCHEDULE" ], "reply": { "content": "Our business hours are 9am - 5pm, Monday to Friday." } }, { "keywords": [ "LOCATION", "ADDRESS" ], "reply": { "content": "We are located at 123 Main St." } } ] } } }, "messaging_poll": { "description": "Messaging poll service that collects responses from contacts to one or more survey questions.", "config": { "$ref": "#/components/schemas/ServiceConfigMessagingPoll" }, "example": { "service_type": "messaging_poll", "name": "Customer Survey", "config": { "response_mode": "keyword", "trigger_keyword": "SURVEY", "questions": [ { "id": "satisfaction", "question_type": "multiple_choice", "body": { "content": "How satisfied are you? Reply 1-5" }, "choices": [ { "code": "5", "conditions": [ { "type": "equals", "value": "5" } ] }, { "code": "4", "conditions": [ { "type": "equals", "value": "4" } ] }, { "code": "3", "conditions": [ { "type": "equals", "value": "3" } ] }, { "code": "2", "conditions": [ { "type": "equals", "value": "2" } ] }, { "code": "1", "conditions": [ { "type": "equals", "value": "1" } ] } ] } ], "end_reply": { "content": "Thank you for completing our survey!" } } } }, "voice_poll": { "description": "Voice poll service that collects responses from contacts via a voice call (IVR), using key presses, voice recordings, or speech-to-text answers to one or more questions.", "config": { "$ref": "#/components/schemas/ServiceConfigVoicePoll" }, "example": { "service_type": "voice_poll", "name": "Customer Voice Survey", "config": { "incoming_call_mode": "none", "start_audio": { "mode": "tts", "text": "Welcome to our customer survey.", "language": "en-US" }, "questions": [ { "id": "satisfaction", "question_type": "keypress", "body": { "mode": "tts", "text": "Press 1 for satisfied, 2 for dissatisfied.", "language": "en-US" }, "choices": [ { "code": "satisfied", "conditions": [ { "type": "equals", "value": "1" } ] }, { "code": "dissatisfied", "conditions": [ { "type": "equals", "value": "2" } ] } ] } ], "end_audio": { "mode": "tts", "text": "Thank you for completing our survey.", "language": "en-US" } } } }, "scheduled_actions": { "description": "Custom Actions service triggered at scheduled times.", "config": { "$ref": "#/components/schemas/ServiceConfigScheduledActions" }, "example": { "service_type": "scheduled_actions", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "auto_reply": { "description": "Auto-reply service that sends a fixed text reply when an incoming message is received.", "config": { "$ref": "#/components/schemas/ServiceConfigAutoReply" }, "example": { "service_type": "auto_reply", "name": "Thanks Auto-Reply", "config": { "reply": { "content": "Thanks for your message! We will respond shortly." } } } }, "call_auto_reply": { "description": "Auto-reply service that sends a fixed text reply when an incoming call is received.", "config": { "$ref": "#/components/schemas/ServiceConfigCallAutoReply" }, "example": { "service_type": "call_auto_reply", "name": "Missed Call Reply", "config": { "reply": { "content": "Sorry we missed your call. We'll get back to you shortly." } } } }, "incoming_message_script": { "description": "Cloud Script service that runs JavaScript code when incoming messages are received.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "incoming_message_script", "name": "My Script", "config": { "code": "function main() {\n sendReply('Hello!');\n return 'Message sent';\n}" } } }, "contact_script": { "description": "Cloud Script service that runs JavaScript code when triggered for a contact.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "contact_script", "name": "Tag Inactive Contacts", "config": { "code": "function main() {\n var lastMessage = project.getMessages({\n contact_id: contact.id,\n direction: 'incoming',\n sort_dir: 'desc'\n }).limit(1).next();\n\n if (lastMessage) {\n var daysSince = (Date.now() - lastMessage.time_created * 1000) / 86400000;\n if (daysSince > 30) {\n contact.addToGroup(project.getOrCreateGroup({name: 'Inactive'}));\n }\n }\n}" } } }, "message_script": { "description": "Cloud Script service that runs JavaScript code when triggered for a message.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "message_script", "config": { "code": "function main() {\n // your code here\n}" } } }, "data_row_script": { "description": "Cloud Script service that runs JavaScript code when triggered for a data table row.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "data_row_script", "config": { "code": "function main() {\n // your code here\n}" } } }, "scheduled_script": { "description": "Cloud Script service that runs JavaScript code at scheduled times.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "scheduled_script", "config": { "code": "function main() {\n // your code here\n}" } } }, "webhook_script": { "description": "Cloud Script service that runs JavaScript code when triggered via webhook from external systems.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "webhook_script", "config": { "code": "function main() {\n // your code here\n}" } } }, "voice_script": { "description": "Cloud Script service triggered when a voice call is received or answered.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "voice_script", "config": { "code": "function main() {\n // your code here\n}" } } }, "ussd_script": { "description": "Cloud Script service triggered when a USSD session is received.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "ussd_script", "config": { "code": "function main() {\n // your code here\n}" } } }, "project_script": { "description": "Cloud Script service that runs JavaScript code when triggered for the project.", "config": { "$ref": "#/components/schemas/ServiceConfigScript" }, "example": { "service_type": "project_script", "config": { "code": "function main() {\n // your code here\n}" } } }, "opt_out_page": { "description": "Opt-Out Page service that provides a mobile web page allowing contacts to unsubscribe.", "config": { "$ref": "#/components/schemas/ServiceConfigOptOutPage" }, "example": { "service_type": "opt_out_page", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "button_page": { "description": "Button Page service that provides a mobile web page with a button that triggers actions when clicked.", "config": { "$ref": "#/components/schemas/ServiceConfigButtonPage" }, "example": { "service_type": "button_page", "config": { "actions": [ { "type": "log", "value": "Service triggered" } ] } } }, "custom_template_instance": { "description": "Service instance created from a reusable service template. Templates allow creating standardized services with configurable parameters.", "config": { "$ref": "#/components/schemas/ServiceConfigCustomTemplateInstance" }, "example": { "service_type": "custom_template_instance", "name": "My Template Instance", "config": { "template_service_id": "SV0123456789abcdef", "params": { "welcome_message": "Hello!", "timeout_hours": 24 } } } } }, "x-action-types": { "add_contact_to_group": { "description": "Adds the current contact to a group. If the group doesn't exist yet, Telerivet will create it.\n\nIf you want to add a contact other than the one who sent the message, add a \"Use another contact\" rule before this rule.", "schema": { "$ref": "#/components/schemas/ActionAddContactToGroup" }, "example": { "type": "add_contact_to_group", "group_name": "subscribers" } }, "add_label_to_message": { "description": "Adds a label to the current message. This makes it easy to segment certain types of messages on your Messages page.", "schema": { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, "example": { "type": "add_label_to_message", "label_name": "support requests" } }, "block_contact": { "description": "Blocks the current contact.", "schema": { "$ref": "#/components/schemas/ActionBlockContact" }, "example": { "type": "block_contact", "send_blocked": true } }, "call_contact": { "description": "Sends a voice call to the current contact using a specified IVR service.", "schema": { "$ref": "#/components/schemas/ActionCallContact" } }, "cancel_scheduled_messages": { "description": "Cancels all scheduled messages to the current contact.\n\nNote this doesn't cancel messages that are scheduled to an entire group. In this case, the contact would need to be removed from the group in order to cancel the message.\n", "schema": { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, "example": { "type": "cancel_scheduled_messages" } }, "condition": { "description": "\nA rule that only matches if a certain condition is true (e.g. the message has a particular keyword or sender). Always combined with one or more other rules.\n\n\"If ... then ...\" rules can use the following types of conditions:\n\n* is\n* is not\n* has word\n* does not have word\n* contains\n* does not contain\n* starts with\n* does not start with\n* ends with\n* does not end with\n* alphabetically before\n* alphabetically after\n* equals\n* does not equal\n* less than\n* greater than\n* less than or equal to\n* greater than or equal to\n* contact is in group\n* contact is not in group\n\nA single \"If ... then ...\" rule can contain multiple conditions, joined together with either 'and' or 'or'.", "schema": { "$ref": "#/components/schemas/ActionCondition" } }, "copy_message_to_project": { "description": "Copies the current incoming message to another project within the same organization.\n\nThis is useful for routing messages to different projects based on message content or contact information, while keeping the original message in the current project.", "schema": { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, "example": { "type": "copy_message_to_project", "project_id": "PJxxxxxxxxxxxxxxxx" } }, "end_session": { "description": "Ends the current USSD session.", "schema": { "$ref": "#/components/schemas/ActionEndSession" }, "example": { "type": "end_session" } }, "end_survey": { "description": "Within a poll service, skips to the end of the survey.", "schema": { "$ref": "#/components/schemas/ActionEndSurvey" }, "example": { "type": "end_survey" } }, "forward_call": { "description": "Forwards the incoming call to another phone number.", "schema": { "$ref": "#/components/schemas/ActionForwardCall" }, "example": { "type": "forward_call", "phone_number": "+16505550123" } }, "hangup": { "description": "Hangs up the phone call.", "schema": { "$ref": "#/components/schemas/ActionHangup" }, "example": { "type": "hangup" } }, "ignore_message": { "description": "Within a poll service, ignores the current message.", "schema": { "$ref": "#/components/schemas/ActionIgnoreMessage" }, "example": { "type": "ignore_message" } }, "log": { "description": "Adds a log message to Telerivet's [service log](/dashboard/service_logs).\n\nTo view the service log, open your [Services page](/dashboard/services) and click More > View logs.\n\nWhen using the \"Test Service\" feature, log messages will be displayed directly in the simulated phone dialog.\n", "schema": { "$ref": "#/components/schemas/ActionLog" }, "example": { "type": "log", "value": "word1 = [[word1]]" } }, "play_audio": { "description": "Plays an audio file in WAV or MP3 format in the voice call, which may be uploaded, linked, or recorded via the Telerivet web app. Alternatively, can use text-to-speech to speak a message.", "schema": { "$ref": "#/components/schemas/ActionPlayAudio" }, "example": { "type": "play_audio", "mode": "file", "audio_url": "http://localhost/_media/sounds/bell2.mp3" } }, "push_to_hubspot": { "description": "Pushes the message to a HubSpot Help Desk inbox, in a conversation associated with the current contact. HubSpot agents can reply directly to send a reply to the contact.", "schema": { "$ref": "#/components/schemas/ActionPushToHubspot" }, "example": { "type": "push_to_hubspot", "integration_id": null, "content": "[[content]]" } }, "push_to_zendesk": { "description": "Pushes the message to a Zendesk support inbox, in a ticket associated with the current contact. Zendesk agents can reply directly to the Zendesk ticket to send a reply to the contact.", "schema": { "$ref": "#/components/schemas/ActionPushToZendesk" }, "example": { "type": "push_to_zendesk", "subdomain": "example", "subject": "Message from [[contact.name]]", "content": "[[content]]" } }, "record_audio": { "description": "Records an audio response from the caller, saves the recording URL as a custom variable on the message, then triggers the associated response handler.", "schema": { "$ref": "#/components/schemas/ActionRecordAudio" }, "example": { "type": "record_audio", "state_id": "input" } }, "remove_contact_from_group": { "description": "Removes the current contact from a group.\n\nIf you want to remove a contact other than the one who sent the message, add a \"Use another contact\" rule before this rule.", "schema": { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, "example": { "type": "remove_contact_from_group", "group_name": "subscribers" } }, "repeat_question": { "description": "Within a poll service, repeats the current question again.", "schema": { "$ref": "#/components/schemas/ActionRepeatQuestion" }, "example": { "type": "repeat_question" } }, "reply": { "description": "Sends a text reply to the sender.\n\nOptionally, the reply can be scheduled after a predefined delay, or sent via a different phone than the one that received the message.", "schema": { "$ref": "#/components/schemas/ActionReply" }, "example": { "type": "reply", "body": { "content": "Hello, [[contact.name]]." } } }, "reply_simple": { "description": "Sends a text reply to the sender (simple version without labels, schedule, or route configuration).", "schema": { "$ref": "#/components/schemas/ActionReplySimple" }, "example": { "type": "reply_simple", "body": { "content": "Hello, [[contact.name]]." } } }, "resend_message": { "description": "Within a service triggered when a message status changes, will automatically resend the current message via the same route or a different route.", "schema": { "$ref": "#/components/schemas/ActionResendMessage" }, "example": { "type": "resend_message" } }, "run_script": { "description": "Runs custom JavaScript code on Telerivet's servers using Telerivet's Cloud Script API.\n\nThis makes it possible to define custom actions such as calling the Telerivet REST API or third-party APIs, or parsing structured data from incoming messages.\n\nFor more details, see the [Cloud Script API documentation](/api/script).\n", "schema": { "$ref": "#/components/schemas/ActionRunScript" }, "example": { "type": "run_script", "code": "var response = httpClient.request(\n \"http://api.coindesk.com/v1/bpi/currentprice.json\");\n\nvar bitcoinInfo = JSON.parse(response.content);\nsendReply(\"1 BTC = $\" + bitcoinInfo.bpi.USD.rate);" } }, "run_subroutine": { "description": "Triggers a set of actions which can be reused multiple times in the same service.", "schema": { "$ref": "#/components/schemas/ActionRunSubroutine" } }, "send_airtime": { "description": "Sends airtime to the current contact if they are on a particular mobile network. Acts like a condition, and allows running other actions if the contact is on one of the supported networks. An 'else' condition can be added below this action to handle contacts that are not on the supported mobile networks.", "schema": { "$ref": "#/components/schemas/ActionSendAirtime" } }, "send_email": { "description": "Sends a plain-text email with custom subject line and body.\n\nEach rule can only send to a single email address; if you need multiple recipients, we recommend setting up a mailing list on your own server.\n\nWhen receiving MMS and chat messages, you can optionally send the multimedia files as email attachments.\n\nTo prevent abuse, it isn't possible to change the 'From' name or email address of the email, although these settings can be configured when using Telerivet on a custom domain.", "schema": { "$ref": "#/components/schemas/ActionSendEmail" }, "example": { "type": "send_email", "to_email": "admin@example.com", "subject": "New message from [[contact.name]]", "body_text": "Phone Number: [[from_number]]\n\n[[content]]" } }, "send_text": { "description": "Sends a text message to any phone number.\n\nOptionally, the message can be scheduled after a predefined delay, or sent via a different phone than the one that received the message.", "schema": { "$ref": "#/components/schemas/ActionSendText" }, "example": { "type": "send_text", "body": { "content": "[[contact.name]] sent you a message: [[content]]." }, "to_number": "+16505550123" } }, "send_text_to_contact": { "description": "Sends a text message to the current contact.", "schema": { "$ref": "#/components/schemas/ActionSendTextToContact" }, "example": { "type": "send_text_to_contact", "body": { "content": "Hello, [[contact.name]]." } } }, "send_text_to_group": { "description": "Sends a SMS message to a group defined on your Contacts page.\n\nOptionally, you can exclude the message sender from receiving the message (common when implementing a group chat system).", "schema": { "$ref": "#/components/schemas/ActionSendTextToGroup" }, "example": { "type": "send_text_to_group", "body": { "content": "[[contact.name]] said: [[content]]." }, "group_name": "subscribers", "exclude_sender": null } }, "send_ussd": { "description": "Sends a USSD request from your Android phone to your mobile network.\n\nOn some mobile networks, USSD requests can be used to check your airtime balance, transfer airtime to other phone numbers, and more.\n\nNote that this requires a compatible Android phone running the Telerivet Gateway app. Also, Telerivet cannot automatically invoke USSD requests that return menus or prompts.", "schema": { "$ref": "#/components/schemas/ActionSendUssd" }, "example": { "type": "send_ussd", "mmi_code": "*104*1000*[[from_number.national_raw]]#" } }, "send_ussd_reply": { "description": "Shows the specified text in the active USSD session. If this action is followed by a 'Wait for response' action, the text will be displayed as part of a USSD prompt.", "schema": { "$ref": "#/components/schemas/ActionSendUssdReply" }, "example": { "type": "send_ussd_reply", "text": "Please enter a response on the keypad." } }, "set_contact": { "description": "Creates or retrieves a contact with a particular phone number, and sets that as the \"current\" contact for subsequent rules.\n\nThis rule is often used to allow your organization's workers to register other people via SMS, and is typically combined with other rules to add the contact to a group and update their contact information.", "schema": { "$ref": "#/components/schemas/ActionSetContact" }, "example": { "type": "set_contact", "phone_number": "[[word2]]" } }, "set_contact_name": { "description": "Updates the name of the current contact in Telerivet.", "schema": { "$ref": "#/components/schemas/ActionSetContactName" }, "example": { "type": "set_contact_name", "name": "[[word3]]" } }, "set_contact_var": { "description": "Updates custom contact information for the current contact (for example, email address or birthdate).\n\nThe rules editor lists the current variable names available for your project. You can also use a new variable name consisting of letters, numbers, and underscores.", "schema": { "$ref": "#/components/schemas/ActionSetContactVar" }, "example": { "type": "set_contact_var", "variable": "email", "value": "[[word4]]" } }, "set_message_var": { "description": "Updates a custom variable for the current message.\n\nWhen triggered from a service that has a response data table (such as a poll service or custom actions with response handlers), custom message variables set via this action are automatically copied as custom variables on the corresponding response data table row. This is the recommended way to store derived or computed values in the response data table.", "schema": { "$ref": "#/components/schemas/ActionSetMessageVar" }, "example": { "type": "set_message_var", "variable": "urgent", "value": "yes" } }, "set_variable": { "description": "Updates the value of any writable variable within the Rules Engine.\n\nOptionally, you can use this rule to perform simple numeric operations between two variables such as addition, subtraction, multiplication and division.\n\nRead-only variables cannot be updated via this rule.\n\n[See available variables](#message_variables)", "schema": { "$ref": "#/components/schemas/ActionSetVariable" }, "example": { "type": "set_variable", "variable": "$foo", "value": "[[word1]]" } }, "skip_to_question": { "description": "Within a poll service, skips to a question outside the normal order.", "schema": { "$ref": "#/components/schemas/ActionSkipToQuestion" }, "example": { "type": "skip_to_question", "question_id": "q3" } }, "star_message": { "description": "Adds a star to the current message. This makes it easy to segment important messages on your Messages page.", "schema": { "$ref": "#/components/schemas/ActionStarMessage" }, "example": { "type": "star_message" } }, "stop": { "description": "Stops processing rules for this message (for this service only).", "schema": { "$ref": "#/components/schemas/ActionStop" }, "example": { "type": "stop" } }, "trigger_contact_service": { "description": "Triggers another service for the current contact.", "schema": { "$ref": "#/components/schemas/ActionTriggerContactService" } }, "trigger_message_service": { "description": "Triggers another service for the current message.", "schema": { "$ref": "#/components/schemas/ActionTriggerMessageService" } }, "trigger_project_service": { "description": "Triggers another service for the current project.", "schema": { "$ref": "#/components/schemas/ActionTriggerProjectService" } }, "use_phone": { "description": "Within a custom route, selects one or more basic routes that can be used to send the message.", "schema": { "$ref": "#/components/schemas/ActionUsePhone" }, "example": { "type": "use_phone", "phone_ids": [ "PN123abc", "PN456def" ] } }, "wait_for_digits": { "description": "Waits for the caller to enter digits on the keypad, saves the input as a custom variable on the message, then triggers the associated response handler.", "schema": { "$ref": "#/components/schemas/ActionWaitForDigits" }, "example": { "type": "wait_for_digits", "state_id": "input", "max_digits": 4 } }, "wait_for_key": { "description": "Waits for the caller to press a single key on the keypad, saves the input as a custom variable on the message, then triggers the associated response handler.", "schema": { "$ref": "#/components/schemas/ActionWaitForKey" }, "example": { "type": "wait_for_key", "state_id": "input" } }, "wait_response": { "description": "Waits for a response from the current contact, then processes the response using another set of actions or conditions. Useful for back-and-forth conversations or data collection that requires the contact to send multiple messages.", "schema": { "$ref": "#/components/schemas/ActionWaitResponse" } }, "wait_ussd_response": { "description": "Prompts the user for input in the active USSD session, saves the response as a custom variable on the message, and triggers the associated response handler.", "schema": { "$ref": "#/components/schemas/ActionWaitUssdResponse" }, "example": { "type": "wait_ussd_response", "state_id": "input" } }, "webhook": { "description": "Makes a HTTP POST request to a URL on your server, passing several POST parameters with information about the current message and contact.\n\nYour webhook script may optionally return a JSON response with a 'messages' property containing an array of messages to send, and a 'variables' property containing variable names and values to update.\n\nFor details, see the [Webhook API documentation](/api/webhook).", "schema": { "$ref": "#/components/schemas/ActionWebhook" }, "example": { "type": "webhook", "url": "http://www.example.com/incoming.php", "secret": "abcdefg" } } } }, "servers": [ { "url": "https://api.telerivet.com", "description": "API server" } ], "security": [ { "basicAuth": [] }, { "oauth2": [] } ], "paths": { "/v1/organizations": { "get": { "summary": "Query organizations", "operationId": "API_queryOrganizations", "description": "Queries organizations accessible to the current user account.", "tags": [ "Organization" ], "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter organizations by name" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/organizations/{organization_id}": { "get": { "summary": "Get organization by ID", "operationId": "API_getOrganizationById", "description": "Retrieves the Telerivet organization with the given ID.", "tags": [ "Organization" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update organization settings", "operationId": "Organization_save", "description": "Saves any fields that have changed for this organization.", "tags": [ "Organization" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the organization", "example": "Example Organization" }, "timezone_id": { "type": "string", "description": "Billing quota time zone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/organizations/{organization_id}/billing": { "get": { "summary": "Get billing details", "operationId": "Organization_getBillingDetails", "description": "Retrieves information about the organization's service plan, including pricing, billing period, current limits, enabled features, overage rates, and any minimum usage fees, as well as the current account balance and payment status.\n\n The `plan_limits` object specifies the maximum allowed usage per metric (e.g. messages per day, contacts, API requests per day) that is included as part of the `plan_price`. Unless otherwise specified, each limit is the total across all projects in the organization (except for `custom_actions`).\n\n When usage reaches a limit, what happens depends on the metric and whether the `soft_limits` feature is enabled in `plan_features`. For some limits, additional usage is allowed and is billed based on `overage_rates` when the `soft_limits` feature is enabled. For other limits, additional usage is blocked until the plan is upgraded to increase the limits.\n\n Additional details about how service plan limits are defined, including what happens when the limits are reached, can be found in the [User Guide](https://guide.telerivet.com/hc/en-us/articles/360038959631-Service-Plan-Limits).", "tags": [ "Organization" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" }, { "name": "usage", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the response also includes a `usage` object with the current usage count for every key in `plan_limits` \u2014 equivalent to calling `getUsage` once per key but in the same round-trip. Omit (or pass false) to skip the usage counters." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "string", "description": "Prepaid account balance" }, "balance_currency": { "type": "string", "description": "Currency of prepaid account balance" }, "plan_name": { "type": "string", "description": "Name of service plan" }, "plan_price": { "type": "string", "description": "Price of service plan" }, "plan_currency": { "type": "string", "description": "Currency of service plan price" }, "plan_rrule": { "type": "string", "description": "Service plan recurrence rule (e.g. FREQ=MONTHLY or FREQ=YEARLY)" }, "plan_paid": { "type": "boolean", "description": "true if the service plan has been paid for the current billing interval; false if it is unpaid (free plans are considered paid)" }, "plan_start_time": { "type": "integer", "format": "unix-timestamp", "description": "Time when the current billing interval started" }, "plan_end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time when the current billing interval ends" }, "plan_suspend_time": { "type": "integer", "format": "unix-timestamp", "description": "Time when the account will be suspended, if the plan remains unpaid after `plan_end_time` (may be null)" }, "plan_limits": { "type": "object", "additionalProperties": true, "description": "Object describing the limits associated with the current service plan. The values are integers, or null. Either `external_messages_day` or `external_messages_period` is included depending on the organization's billing mode (per-day vs. per-plan-period messaging quota). Each key:\n\n- `contacts`: Stored contacts \u2014 The maximum number of contacts stored in your contact database at any time. Each contact can have a name, phone number, and up to 100 custom fields, and can be added to groups. By default, a contact is automatically created for each phone number you communicate with, as long as there is space in your contact database. Automatic contact creation can be disabled in the project settings if you don't need to store contacts. You can send messages to an unlimited number of different phone numbers if you don't store them in your contact database.\n- `phones`: Routes \u2014 The maximum number of different routes that your organization uses to send or receive messages through Telerivet, including Android phones, virtual numbers, alphanumeric sender IDs, SMS shortcodes, and integrations with chat apps like WhatsApp. On service plans that support multiple routes, you can distribute messages among different routes for higher volume, geographic reach, or better rates.\n- `active_services`: Active automated services \u2014 The number of automated services that run in response to certain events, such as when a new message is received, when a message's status changes, or when triggered by a user. Common types of automations like polls and auto-replies can be created from built-in templates. Custom actions can be created using a drag-and-drop flow builder, JavaScript, or a webhook.\n- `users`: User logins \u2014 The maximum number of user accounts you can add for people in your organization to log in and use Telerivet. Each user account can have its own permissions.\n- `stored_messages`: Stored messages \u2014 The total number of messages stored in your Telerivet account, including scheduled messages. You can delete old or unneeded messages to stay under this limit.\n- `service_invocations_day`: Daily service invocations \u2014 The maximum number of times automated services can run per day, excluding Webhook API services. This includes service rules triggered by incoming messages, scheduled triggers, and manual invocations. The counter resets at midnight in your organization's timezone.\n- `api_requests_day`: Daily API requests \u2014 The maximum number of API requests your organization can make per day, counting both REST API and Webhook API requests. The quota resets daily at midnight in the organization's time zone. If you pay Telerivet directly for each message, REST API requests to send messages, and Webhook API requests to receive notifications of incoming messages and delivery reports, are exempt from this limit.\n- `projects`: Projects \u2014 Each project represents an independent mobile messaging system. Each project has its own messages, contacts, routes, and services, and its own set of user permissions. If necessary, you can add multiple projects under one organization and one billing plan.\n- `data_rows`: Rows in custom data tables \u2014 Custom data tables are used to store responses to polls and other automated services. You can also import your own data to build data-driven automations.\n- `script_module_mb`: Cloud Script module storage quota (MB) \u2014 Storage quota for Cloud Script modules \u2014 code modules that you push to Telerivet to run as part of automated services. Measured as the total size of all module files across the organization.\n- `stored_file_mb`: File storage quota (MB) \u2014 Storage quota for files uploaded to Telerivet, including media attachments sent or received in messages.\n- `custom_actions`: Custom actions per service \u2014 The maximum number of custom actions or conditions allowed per automated service. Custom actions extend services with logic written in a drag-and-drop flow builder, JavaScript, or webhooks. Plans with the Advanced Automation feature have no per-service limit.\n- `groups`: Contact groups \u2014 The maximum number of contact groups. Groups are used to organize contacts and to send messages to many recipients at once.\n- `custom_contact_fields`: Custom contact fields \u2014 The maximum number of custom fields that can be defined for contacts. Custom fields store extra information about contacts beyond the built-in name and phone number \u2014 for example, an account ID, language preference, or any project-specific attribute.\n- `external_messages_day`: Included Messages/Day - Bring Your Own Connectivity \u2014 The maximum number of messages that can be sent or received per day when using your own connectivity provider or an Android phone with the Telerivet Gateway app (not when paying Telerivet for each message). The counter resets at midnight in your organization's timezone. This limit applies when the plan's billing mode has a per-day messaging quota.\n- `external_messages_period`: Included Messages/Plan Period - Bring Your Own Connectivity \u2014 The maximum number of messages that can be sent or received per plan period (typically monthly or yearly) when using your own connectivity provider or an Android phone with the Telerivet Gateway app (not when paying Telerivet for each message). This limit applies when the plan has a per-plan-period messaging quota. Each sent or received SMS message part, voice call, USSD session, chat app message, or MMS message is counted as one message; multi-part SMS messages are counted based on the number of SMS parts in the message.\n- `ai_chat_credits_day`: AI chat credits/day" }, "plan_features": { "type": "object", "additionalProperties": true, "description": "Object describing which platform features are enabled for this organization. The keys are string feature IDs and the values are booleans. Available features:\n\n- `direct_connectivity`: Direct Connectivity \u2014 Use Telerivet-managed phone routes where Telerivet handles billing with upstream messaging gateways on your behalf, instead of requiring you to bring your own gateway credentials.\n- `airtime_transfer`: Airtime Topup & Transfer \u2014 Send airtime to prepaid mobile phones as a reward or participation incentive, or top-up the airtime on your own SIM card directly from Telerivet. (Requires Pro plan or above)\n- `click_tracking`: Click Tracking \u2014 Shorten links and track which contacts clicked a link in your message.\n- `custom_gateway`: Custom Gateways \u2014 Integrate with an SMS shortcode or another gateway API. Telerivet can integrate with both HTTP or SMPP messaging APIs, and can configure VPN connections directly with mobile networks if necessary. (Integration fee varies depending on API - contact us)\n- `custom_logo`: Custom Logo \u2014 Replace the Telerivet logo in the web app with your own logo. (Requires Pro plan or above)\n- `custom_domain`: Custom Domain Name \u2014 Access your Telerivet account from your own domain name like sms.example.com, and hide Telerivet branding from users. Configure a custom domain for branded short links. (Contact us for pricing)\n- `soft_limits`: Soft Limits \u2014 Allow exceeding your plan's daily, monthly, or annual limits by paying for extra messages, API requests, or service invocations.\n- `auto_resend`: Automatic Message Resend & Failover \u2014 Configure custom rules to automatically resend failed messages and failover between routes. (Requires plan with Advanced custom automation)\n- `export_storage`: Cloud Data Export \u2014 Automatically export and backup messages, contacts, and other data to the cloud. Connect your own Amazon Web Services S3 account for data storage. (Requires plan with Advanced custom automation)\n- `static_ip_address`: Static IP Address \u2014 Configure Telerivet to use a static IP address for outbound HTTP requests if you need to allow inbound traffic from specific IP addresses in your firewall. (Requires plan with Advanced custom automation)\n- `script_modules`: Cloud Script Modules \u2014 Run Cloud Script API code from an external codebase hosted on GitHub, or push code to Telerivet directly from your development environment. Use source control to track version history. (Requires plan with Advanced custom automation)\n- `service_templates`: Service Templates \u2014 Create reusable automated services that can be shared with multiple projects and organizations. (Contact us for pricing)\n- `single_sign_on`: SAML Single Sign-On \u2014 Allow users to log in via your organization's single sign-on identity provider (SAML 2.0). (Contact us for pricing)\n- `contact_sync`: Contact Data Sync \u2014 Synchronize contact information and opt-out status across multiple Telerivet projects. (Requires Growth plan or above)\n- `external_airtime_providers`: External Airtime Providers \u2014 Configure airtime providers in your projects using your own credentials with an external airtime provider, in addition to (or instead of) Telerivet-managed airtime.\n- `wire_payments`: Wire Payments \u2014 Pay Telerivet invoices via bank wire transfer in addition to credit card and other online payment methods.\n- `custom_dashboards`: Custom Dashboards \u2014 Create custom dashboards with charts and metrics showing Telerivet usage and providing business intelligence about the results of your campaigns. (Requires Pro plan or above)\n- `branded_short_links`: Branded Short Links \u2014 Configure a custom domain name for short links, instead of using the default domain (rvt.me). (Requires Growth plan or above)\n- `custom_solutions`: Custom Solution Development \u2014 Work with Telerivet's professional services team to implement a custom solution for your business needs. (Contact us for pricing)" }, "overage_rates": { "type": "object", "additionalProperties": true, "description": "Per-unit overage rates billed when usage exceeds the corresponding plan limit. Only present when the `soft_limits` feature is enabled in `plan_features` \u2014 without `soft_limits`, reaching a limit blocks further usage until the counter resets rather than accruing per-unit charges, so the rates would not apply and the field is omitted entirely. When present, each entry is an object with `amount` and `currency` properties, where `amount` is the positive per-unit cost in `currency`, or null if no rate is configured. Keys:\n\n- `message`: Cost per external (bring your own connectivity) message sent or received beyond the daily limit (`plan_limits.external_messages_day`) or per-period limit (`plan_limits.external_messages_period`).\n- `api_request`: Cost per REST API request beyond `plan_limits.api_requests_day`.\n- `service_invocation`: Cost per automated-service invocation beyond `plan_limits.service_invocations_day`." }, "minimum_usage_fees": { "type": "array", "items": { "type": "object", "properties": { "description": { "type": "string", "description": "Human-readable description of the minimum usage fee." }, "amount": { "type": "number", "description": "Minimum usage amount per billing cycle, as a positive number in the fee's currency." }, "currency": { "type": "string", "description": "Currency code of the minimum usage amount." } } }, "description": "Array of minimum usage fees configured for this organization. Each fee guarantees a minimum amount of usage-based billing per billing cycle (the period from `plan_start_time` to `plan_end_time`, recurring per `plan_rrule`) for a particular set of usage categories \u2014 for example, a monthly minimum on per-message fees via a particular provider. If the actual usage-based charges across the fee's categories add up to less than the minimum during a billing cycle, the shortfall is billed up to the minimum amount, and added to the organization's recurring billing alongside the plan price. If actual usage exceeds the minimum, no additional minimum-usage charge is applied for that cycle. The array is empty when no minimum usage fees are configured." }, "recurring_billing_enabled": { "type": "boolean", "description": "True if recurring billing is enabled, false otherwise" }, "auto_refill_enabled": { "type": "boolean", "description": "True if auto-refill is enabled, false otherwise" }, "usage": { "type": "object", "additionalProperties": true, "description": "Object mapping each `plan_limits` key to the current integer usage count for that metric \u2014 present only when the request was made with `usage=true`. Includes either `external_messages_day` or `external_messages_period` (matching whichever the organization's billing mode produces in `plan_limits`), not both. Reset schedules and the per-service `custom_actions` semantics described on getUsage apply here as well." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/organizations/{organization_id}/message_stats": { "get": { "summary": "Get historical message statistics for all projects in organization", "operationId": "Organization_getMessageStats", "description": "Retrieves statistics about messages sent or received via Telerivet. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone, and does not contain message statistics for the current day.", "tags": [ "Message" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" }, { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "Start date of message statistics, in YYYY-MM-DD format", "required": true, "example": "2022-01-01" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "End date of message statistics (inclusive), in YYYY-MM-DD format", "required": true, "example": "2022-12-31" }, { "name": "rollup", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "year", "all" ], "default": "day" }, "description": "Date interval to group by", "example": "month" }, { "name": "properties", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "org_id", "org_name", "org_industry", "project_id", "project_name", "user_id", "user_email", "user_name", "phone_id", "phone_name", "phone_type", "direction", "source", "status", "network_code", "network_name", "message_type", "service_id", "service_name", "simulated", "link" ] } }, "style": "form", "explode": false, "description": "Comma separated list of properties to group by", "example": "phone_name,status,direction" }, { "name": "metrics", "in": "query", "schema": { "type": "string" }, "style": "form", "explode": false, "description": "Comma separated list of metrics to return (summed for each distinct value of the requested properties). Supported metrics are `count` (the number of messages), `num_parts` (the number of SMS parts), `duration` (the total duration of calls, in seconds), and `price.` (the total price of messages priced in the specified ISO 4217 currency, e.g. `price.USD`). Amounts are not converted between currencies: each `price.` metric only includes messages priced in the specified currency.", "required": true, "example": "count,num_parts,price.USD" }, { "name": "filters", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Key-value pairs of properties and corresponding values; the returned statistics will only include messages where the property matches the provided value. Only the following properties are supported for filters: `user_id`, `phone_id`, `direction`, `source`, `status`, `service_id`, `simulated`, `message_type`, `network_code`" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "intervals": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "integer", "description": "UNIX timestamp of the start of the interval" }, "end_time": { "type": "integer", "description": "UNIX timestamp of the end of the interval, exclusive" }, "start_date": { "type": "string", "description": "Date of the start of the interval in YYYY-MM-DD format" }, "end_date": { "type": "string", "description": "Date of the end of the interval in YYYY-MM-DD format, inclusive" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": true, "description": "Key/value pairs for each distinct value of the requested properties" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Key/value pairs for each requested metric" } } }, "description": "Array of groups for each combination of requested property values" } } }, "description": "List of objects representing each date interval containing at least one message matching the filters." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/organizations/{organization_id}/projects": { "post": { "summary": "Create a project", "operationId": "Organization_createProject", "description": "Creates a new project.\n\n Some project settings are not currently possible to configure via the API, and can only be edited via the web app after the project is created.", "tags": [ "Project" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the project to create, which must be unique in the organization.", "example": "Example Project" }, "timezone_id": { "type": "string", "description": "Default TZ database timezone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). This timezone is used when computing statistics by date.", "example": "America/Los_Angeles" }, "url_slug": { "type": "string", "description": "Unique string used as a component of the project's URL in the Telerivet web app (required length: 3-18 characters). If not provided, a URL slug will be generated automatically.", "example": "asdf" }, "auto_create_contacts": { "type": "boolean", "description": "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.", "default": true }, "message_retention_days": { "type": "integer", "description": "Number of days to retain messages in this project. Messages older than this will be automatically deleted. If null or not provided, messages will be retained forever.", "example": 90 }, "short_link_scheme": { "type": "boolean", "description": "If true (the default), short links in messages will include the scheme (e.g., 'https://rvt.me/xxxxxxxxx'). If false, short links will not include the scheme (e.g., 'rvt.me/xxxxxxxxx').", "default": true }, "vars": { "type": "string", "description": "Custom variables and values to set for this project" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Query projects in organization", "operationId": "Organization_queryProjects", "description": "Queries projects in this organization.", "tags": [ "Organization" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter projects by name" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/organizations/{organization_id}/usage/{usage_type}": { "get": { "summary": "Get current usage", "operationId": "Organization_getUsage", "description": "Retrieves the current usage count associated with a particular service plan limit.\n\n The available `usage_type` values are the same as the keys returned in `plan_limits` from the getBillingDetails method, so each call returns the current value of the corresponding limit's counter.\n\n Notes:\n\n - `external_messages_day` and `external_messages_period` reset on different schedules: daily counters reset at midnight in the organization's timezone; period counters reset at the start of the next plan period (`plan_start_time` to `plan_end_time` from `getBillingDetails`).\n - `custom_actions` is the highest custom-action count across any single active service in the organization (since the corresponding limit is enforced per service, not per organization).\n - `messages_day` is retained as a deprecated alias for `external_messages_day`", "tags": [ "Organization" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" }, { "name": "usage_type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "contacts", "phones", "active_services", "users", "stored_messages", "service_invocations_day", "api_requests_day", "projects", "data_rows", "script_module_mb", "stored_file_mb", "custom_actions", "groups", "custom_contact_fields", "external_messages_day", "external_messages_period", "ai_chat_credits_day" ] }, "description": "Usage type. Same as the keys returned in `plan_limits` from `Organization.getBillingDetails`." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "integer" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/organizations/{organization_id}/usage_history": { "get": { "summary": "Get usage history", "operationId": "Organization_getUsageHistory", "description": "Retrieves the daily history of the usage count associated with a particular service plan limit.\n\n Telerivet stores a snapshot of each organization's usage once per day, shortly after midnight in the organization's time zone. For usage types that are counted per day (`external_messages_day`, `api_requests_day`, `service_invocations_day`, and `ai_chat_credits_day`), each entry contains the usage counted during that entire day. For all other usage types, each entry contains the usage count at the time the snapshot was recorded.\n\n The maximum supported date range is 500 days between start_date and end_date. If the requested date range includes the current time, the response will also include a final entry with `current: true` containing the live usage count computed at the time of the API request.\n\n Usage snapshots are only recorded while an organization is active, so an entry may not be available for every date in the requested range.", "tags": [ "Organization" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Organization" }, { "name": "usage_type", "in": "query", "schema": { "type": "string", "enum": [ "contacts", "phones", "active_services", "users", "stored_messages", "service_invocations_day", "api_requests_day", "projects", "data_rows", "script_module_mb", "stored_file_mb", "custom_actions", "groups", "custom_contact_fields", "external_messages_day", "external_messages_period", "ai_chat_credits_day" ] }, "description": "Usage type, corresponding to the keys in the `plan_limits` property returned by getBillingDetails.", "required": true, "example": "external_messages_day" }, { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "Start date of usage history, in YYYY-MM-DD format (in the organization's time zone)", "required": true, "example": "2026-01-01" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "End date of usage history (inclusive), in YYYY-MM-DD format (in the organization's time zone)", "required": true, "example": "2026-01-31" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "timezone_id": { "type": "string", "description": "The organization's time zone ID, used to determine the date associated with each entry" }, "usage_type": { "type": "string", "description": "The usage type from the request" }, "history": { "type": "array", "items": { "type": "object", "properties": { "time_counted": { "type": "integer", "description": "UNIX timestamp when the usage was counted" }, "date": { "type": "string", "description": "Date associated with time_counted in the organization's time zone, in YYYY-MM-DD format" }, "current": { "type": "boolean", "description": "True for the final entry containing the live usage count at the time of the API request; false for entries from stored daily snapshots" }, "value": { "type": "integer", "description": "Usage count that applies toward the service plan limit (the same counter returned by [getUsage](#Organization.getUsage))" }, "simulated_value": { "type": "integer", "description": "Usage associated with simulated routes, which does not apply toward the service plan limit (null when not applicable to the usage type)" }, "exempt_value": { "type": "integer", "description": "Usage that is exempt from the service plan limit (null when not applicable to the usage type)" }, "total_value": { "type": "integer", "description": "Total usage, including `value`, `simulated_value`, and `exempt_value`" }, "limit": { "type": "integer", "description": "Value of the corresponding service plan limit at the time the usage was counted (null if unlimited)" } } }, "description": "List of usage entries in chronological order, one for each daily usage snapshot recorded within the requested date range (plus the live usage entry if the range includes the current time)." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects": { "get": { "summary": "Query projects", "operationId": "API_queryProjects", "description": "Queries projects accessible to the current user account.", "tags": [ "Project" ], "parameters": [ { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter projects by name" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}": { "get": { "summary": "Get project by ID", "operationId": "API_getProjectById", "description": "Retrieves the Telerivet project with the given ID.", "tags": [ "Project" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update project details", "operationId": "Project_save", "description": "Updates writable fields on the given project.", "tags": [ "Project" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the project", "example": "Example Project" }, "timezone_id": { "type": "string", "description": "Default TZ database timezone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "url_slug": { "type": "string", "description": "Unique string used as a component of the project's URL in the Telerivet web app (required length: 3-18 characters)", "example": "asdf" }, "default_route_id": { "type": "string", "description": "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." }, "auto_create_contacts": { "type": "boolean", "description": "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.", "example": true }, "message_retention_days": { "type": "integer", "description": "Number of days to retain messages in this project. Messages older than this will be automatically deleted. If null, messages will be retained forever.", "example": 90 }, "short_link_scheme": { "type": "boolean", "description": "If true (the default), short links in messages will include the scheme (e.g., 'https://rvt.me/xxxxxxxxx'). If false, short links will not include the scheme (e.g., 'rvt.me/xxxxxxxxx').", "example": true }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/airtime_stats": { "get": { "summary": "Get historical airtime transaction statistics", "operationId": "Project_getAirtimeStats", "description": "Retrieves statistics about airtime transactions sent via Telerivet. This endpoint returns historical data for successful transactions that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include statistics for the current day so far.", "tags": [ "AirtimeTransaction" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "Start date of airtime statistics, in YYYY-MM-DD format", "required": true, "example": "2022-01-01" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "End date of airtime statistics (inclusive), in YYYY-MM-DD format", "required": true, "example": "2022-12-31" }, { "name": "rollup", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "year", "all" ], "default": "day" }, "description": "Date interval to group by", "example": "month" }, { "name": "properties", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "country", "operator_name", "product_id", "provider_id", "provider_category", "category_name" ] } }, "style": "form", "explode": false, "description": "Comma separated list of properties to group by. The `provider_category` property combines the provider type and category ID (e.g. `main.airtime.dtone/1`); also group by `category_name` to return the category's display name.", "example": "country,operator_name" }, { "name": "metrics", "in": "query", "schema": { "type": "string" }, "style": "form", "explode": false, "description": "Comma separated list of metrics to return (summed for each distinct value of the requested properties). Supported metrics are `count` (the number of successful transactions), `value.` (the face value of the airtime received by the recipients, e.g. `value.KES`), and `price.` (the amount charged for the transactions, e.g. `price.USD`). Amounts are not converted between currencies: each `value`/`price` metric only includes transactions denominated in the specified ISO 4217 currency, and transactions without a numeric currency value (such as bundles) are not included in any `value` metric.", "required": true, "example": "count,value.KES,price.USD" }, { "name": "filters", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Key-value pairs of properties and corresponding values; the returned statistics will only include successful airtime transactions where the property matches the provided value. Only the following properties are supported for filters: `country`, `operator_name`, `product_id`, `provider_id`, `provider_category`" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "intervals": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "integer", "description": "UNIX timestamp of the start of the interval" }, "end_time": { "type": "integer", "description": "UNIX timestamp of the end of the interval, exclusive" }, "start_date": { "type": "string", "description": "Date of the start of the interval in YYYY-MM-DD format" }, "end_date": { "type": "string", "description": "Date of the end of the interval in YYYY-MM-DD format, inclusive" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": true, "description": "Key/value pairs for each distinct value of the requested properties" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Key/value pairs for each requested metric" } } }, "description": "Array of groups for each combination of requested property values" } } }, "description": "List of objects representing each date interval containing at least one successful airtime transaction matching the filters." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/airtime_transactions": { "get": { "summary": "Query airtime transactions", "operationId": "Project_queryAirtimeTransactions", "description": "Returns information about each airtime transaction.", "tags": [ "AirtimeTransaction" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "time_created[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter transactions created on or after a particular time" }, { "name": "time_created[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter transactions created before a particular time" }, { "name": "contact_id", "in": "query", "schema": { "type": "string" }, "description": "Filter transactions sent to a particular contact" }, { "name": "to_number", "in": "query", "schema": { "type": "string" }, "description": "Filter transactions sent to a particular phone number" }, { "name": "service_id", "in": "query", "schema": { "type": "string" }, "description": "Filter transactions sent by a particular service" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "queued", "processing", "submitted", "successful", "failed", "cancelled", "pending_payment", "pending_approval" ] }, "description": "Filter transactions by status" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AirtimeTransaction" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/airtime_transactions/{id}": { "get": { "summary": "Get airtime transaction by ID", "operationId": "Project_getAirtimeTransactionById", "description": "Gets an airtime transaction by ID", "tags": [ "AirtimeTransaction" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the airtime transaction" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AirtimeTransaction" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/broadcasts": { "get": { "summary": "Query broadcasts", "operationId": "Project_queryBroadcasts", "description": "Queries broadcasts within the given project.\n\n Note: To be notified of new broadcasts as they are sent, use the [Webhook API](https://telerivet.com/api/webhook#broadcast).", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "time_created[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter broadcasts created on or after a particular time" }, { "name": "time_created[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter broadcasts created before a particular time" }, { "name": "last_message_time[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter broadcasts with most recent message on or after a particular time" }, { "name": "last_message_time[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter broadcasts with most recent message before a particular time" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "last_message_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Broadcast" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/broadcasts/{id}": { "get": { "summary": "Get broadcast by ID", "operationId": "Project_getBroadcastById", "description": "Retrieves the broadcast with the given ID.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the broadcast" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/broadcasts/{id}/cancel": { "post": { "summary": "Cancel sending a broadcast", "operationId": "Broadcast_cancel", "description": "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).", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Broadcast" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/campaigns": { "get": { "summary": "Query campaigns", "operationId": "Project_queryCampaigns", "description": "Queries campaigns within the given project.", "tags": [ "Campaign" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter campaigns by name" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "draft", "scheduled", "sent", "pending_review" ] }, "description": "Filter campaigns by status" }, { "name": "campaign_type", "in": "query", "schema": { "type": "string", "enum": [ "broadcast_text", "broadcast_call", "broadcast_svc", "relative", "anniversary" ] }, "description": "Filter campaigns by type" }, { "name": "group_id", "in": "query", "schema": { "type": "string", "description": "ID of Group" }, "description": "Filter campaigns by the recipient group" }, { "name": "label_id", "in": "query", "schema": { "type": "string", "description": "ID of Label" }, "description": "Filter campaigns by an associated label" }, { "name": "time_created[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter campaigns created on or after a particular time" }, { "name": "time_created[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter campaigns created before a particular time" }, { "name": "schedule_time[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter broadcast campaigns scheduled on or after a particular time" }, { "name": "schedule_time[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter broadcast campaigns scheduled before a particular time" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name", "schedule_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a campaign", "operationId": "Project_createCampaign", "description": "Creates a new draft campaign, without sending it.", "tags": [ "Campaign" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "campaign_type": { "type": "string", "description": "Type of campaign to create", "enum": [ "broadcast_text", "broadcast_call", "broadcast_svc", "relative", "anniversary" ], "example": "broadcast_text" }, "name": { "type": "string", "description": "Name of the campaign", "example": "My Campaign" }, "group_id": { "type": "string", "description": "ID of the group of contacts to send the campaign to", "example": "CG1234567890abcdef" }, "exclude_group_id": { "type": "string", "description": "ID of a group of contacts to exclude from this campaign" }, "route_id": { "type": "string", "description": "ID of the phone or route to send the campaign from", "example": "PN11586298d3412adf" }, "timezone_id": { "type": "string", "description": "ID of the timezone to use for scheduling" }, "label_ids": { "type": "string", "description": "IDs of labels to apply to messages sent by this campaign" }, "respondent_group_id": { "type": "string", "description": "ID of the group to add contacts to after they respond" }, "clicked_group_id": { "type": "string", "description": "ID of the group to add contacts to after they click a link" }, "schedule_mode": { "type": "string", "description": "Indicates whether the campaign should be sent immediately or at a future time (broadcast campaigns only). If `schedule_time` is set, `schedule_mode` is automatically set to `at_time`. If `schedule_mode` is set to `immediate` or `null`, `schedule_time` is automatically cleared.\n\n Note that the campaign will not actually be sent or scheduled until the API method is called to send the campaign.", "enum": [ "immediate", "at_time" ] }, "schedule_time": { "type": "integer", "format": "unix-timestamp", "description": "When the campaign is scheduled to be sent, as a UNIX timestamp (broadcast campaigns only). Setting this to a non-null value automatically sets `schedule_mode` to `at_time`.\n\n Note that the campaign will not actually be scheduled until the API method is called to schedule the campaign." }, "content": { "type": "string", "description": "Text content of the message (`broadcast_text` campaigns), or the text-to-speech text for voice calls (`broadcast_call` campaigns). May contain variables like `[[contact.name]]`.\n\n(See available variables)", "example": "Hello world" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n Use a https:// or http:// URL for media files that are already accessible via the internet.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project." }, "file_id": { "type": "string", "description": "ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required." }, "type": { "type": "string", "description": "MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media. Ignored if file_id is provided." } } }, "description": "Array of media attachments (`broadcast_text` campaigns only)." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message (`broadcast_text` campaigns only). See Route-Specific Parameters." }, "track_clicks": { "type": "boolean", "description": "Whether to shorten links and track link clicks (`broadcast_text` campaigns only)." }, "short_link_params": { "type": "object", "properties": { "domain": { "type": "string", "description": "Custom domain for short links." }, "expiration_sec": { "type": "integer", "description": "Expiration time in seconds for short links." } }, "description": "Parameters for short links when `track_clicks` is enabled (`broadcast_text` campaigns only)." }, "audio_url": { "type": "string", "description": "URL of an MP3 file to play for voice calls (`broadcast_call` campaigns only)." }, "tts_lang": { "type": "string", "description": "Language for text-to-speech voice calls (`broadcast_call` campaigns only).", "enum": [ "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": { "type": "string", "description": "Voice for text-to-speech voice calls (`broadcast_call` campaigns only).", "enum": [ "female", "male" ] }, "date_variable": { "type": "string", "description": "Custom contact variable storing date or date/time values relative to which messages will be scheduled (`relative` and `anniversary` campaigns only)" }, "items": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "description": "Type of message to send: `\"text\"`, `\"service\"`, or `\"call\"`" }, "offset_count": { "type": "integer", "description": "The number of days/weeks/months/years to adjust the date of the scheduled message relative to the date stored in the contact variable. May be positive (after), negative (before), or zero (on the date)." }, "offset_scale": { "type": "string", "description": "The type of interval for the offset (I=minutes, D=day, W=week, M=month, Y=year)." }, "time_of_day": { "type": "string", "description": "Time of day when messages will be sent, in HH:MM format (with hours from 00 to 23)." }, "content": { "type": "string", "description": "Text content of the message (when `mode` is `\"text\"`), or the text-to-speech text for voice calls (when `mode` is `\"call\"`). May contain variables like `[[contact.name]]`.\n\n [(See available variables)](#variables)" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n Use a https:// or http:// URL for media files that are already accessible via the internet.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project." }, "file_id": { "type": "string", "description": "ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required." }, "type": { "type": "string", "description": "MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media. Ignored if file_id is provided." } } }, "description": "Array of media attachments (when `mode` is `\"text\"`)." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message (when `mode` is `\"text\"`). See [Route-Specific Parameters](#route_params)." }, "track_clicks": { "type": "boolean", "description": "Whether to shorten links and track link clicks (when `mode` is `\"text\"`)." }, "short_link_params": { "type": "object", "properties": { "domain": { "type": "string", "description": "Custom domain for short links. Must be configured for this project." }, "expiration_sec": { "type": "integer", "description": "Expiration time in seconds for short links." } }, "description": "Parameters for short links when `track_clicks` is enabled (when `mode` is `\"text\"`)." }, "service_id": { "type": "string", "description": "ID of the service to trigger (when `mode` is `\"service\"` or `\"call\"`)" }, "audio_url": { "type": "string", "description": "URL of an MP3 file to play for voice calls (when `mode` is `\"call\"`)" }, "tts_lang": { "type": "string", "description": "Language for text-to-speech voice calls (when `mode` is `\"call\"`)" }, "tts_voice": { "type": "string", "description": "Voice for text-to-speech voice calls (when `mode` is `\"call\"`)" } } }, "description": "Array of campaign items (`relative` and `anniversary` campaigns only)." }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables and values to set for this campaign. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } }, "required": [ "campaign_type" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/campaigns/{id}": { "post": { "summary": "Update campaign details", "operationId": "Campaign_save", "description": "Updates writable fields on the given campaign.", "tags": [ "Campaign" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Campaign" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the campaign, which must be unique within the project. The campaign name is only visible within Telerivet, and does not appear in the messages sent to contacts.", "example": "Test Campaign" }, "group_id": { "type": "string", "description": "ID of the group of contacts that the campaign will be sent to", "example": "CG02139128391fa" }, "exclude_group_id": { "type": "string", "description": "ID of a group of contacts to exclude from the campaign" }, "route_id": { "type": "string", "description": "ID of the phone or route used to send the campaign", "example": "RT2a586298d3412adf" }, "respondent_group_id": { "type": "string", "description": "ID of a group to add contacts to after they respond to the campaign" }, "clicked_group_id": { "type": "string", "description": "ID of a group to add contacts to after they click a link in the campaign" }, "label_ids": { "type": "string", "description": "List of IDs of labels applied to messages sent by this campaign" }, "schedule_mode": { "type": "string", "description": "Indicates whether the campaign should be sent immediately or at a future time (applies to broadcast campaign types). If `schedule_time` is set, `schedule_mode` is automatically set to `at_time`. If `schedule_mode` is set to `immediate` or `null`, `schedule_time` is automatically cleared.\n\n Note that after setting schedule_mode to \"immediate\" on a campaign with the `draft` status, the campaign will not actually be sent until the API method is called to send the campaign.", "enum": [ "immediate", "at_time" ], "example": "immediate" }, "schedule_time": { "type": "integer", "format": "unix-timestamp", "description": "The time to send the campaign, as a UNIX timestamp (applies to broadcast campaign types). Setting this to a non-null value automatically sets `schedule_mode` to `at_time`.\n\n Note that after setting schedule_time on a campaign with the `draft` status, the campaign will not actually be scheduled until the API method is called to schedule the campaign." }, "content": { "type": "string", "description": "Text content of the message (applies to `broadcast_text` campaigns), or the text-to-speech text for voice calls (applies to `broadcast_call` campaigns). May contain variables like `[[contact.name]]`.\n\n (See available variables)", "example": "Hello world" }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message (applies to `broadcast_text` campaigns). See Route-Specific Parameters." }, "track_clicks": { "type": "boolean", "description": "Whether to shorten links and track link clicks (applies to `broadcast_text` campaigns)." }, "short_link_params": { "type": "object", "properties": { "domain": { "type": "string", "description": "Custom domain for short links. Must be configured for this project." }, "expiration_sec": { "type": "integer", "description": "Expiration time in seconds for short links." } }, "description": "Parameters for short links when `track_clicks` is enabled (applies to `broadcast_text` campaigns)." }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call (applies to `broadcast_call` campaigns)" }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice (applies to `broadcast_call` campaigns)", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice (applies to `broadcast_call` campaigns)", "enum": [ "female", "male" ] }, "date_variable": { "type": "string", "description": "Custom contact variable storing date or date/time values relative to which messages will be scheduled (applies to `relative` and `anniversary` campaigns)" }, "items": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "description": "Type of message to send: `\"text\"`, `\"service\"`, or `\"call\"`" }, "offset_count": { "type": "integer", "description": "The number of days/weeks/months/years to adjust the date of the scheduled message relative to the date stored in the contact variable. May be positive (after), negative (before), or zero (on the date)." }, "offset_scale": { "type": "string", "description": "The type of interval for the offset (I=minutes, D=day, W=week, M=month, Y=year)." }, "time_of_day": { "type": "string", "description": "Time of day when messages will be sent, in HH:MM format (with hours from 00 to 23)." }, "content": { "type": "string", "description": "Text content of the message (when `mode` is `\"text\"`), or the text-to-speech text for voice calls (when `mode` is `\"call\"`). May contain variables like `[[contact.name]]`.\n\n [(See available variables)](#variables)" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments (when `mode` is `\"text\"`)." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message (when `mode` is `\"text\"`). See [Route-Specific Parameters](#route_params)." }, "track_clicks": { "type": "boolean", "description": "Whether to shorten links and track link clicks (when `mode` is `\"text\"`)." }, "short_link_params": { "type": "object", "properties": { "domain": { "type": "string", "description": "Custom domain for short links. Must be configured for this project." }, "expiration_sec": { "type": "integer", "description": "Expiration time in seconds for short links." } }, "description": "Parameters for short links when `track_clicks` is enabled (when `mode` is `\"text\"`)." }, "service_id": { "type": "string", "description": "ID of the service to trigger (when `mode` is `\"service\"` or `\"call\"`)" }, "audio_url": { "type": "string", "description": "URL of an MP3 file to play for voice calls (when `mode` is `\"call\"`)" }, "tts_lang": { "type": "string", "description": "Language for text-to-speech voice calls (when `mode` is `\"call\"`)" }, "tts_voice": { "type": "string", "description": "Voice for text-to-speech voice calls (when `mode` is `\"call\"`)" } } }, "description": "Array of campaign items (applies to `relative` and `anniversary` campaigns). Each item defines a scheduled message with timing and content." }, "timezone_id": { "type": "string", "description": "The ID of the timezone used for scheduling messages in this campaign, or null to use the project's default timezone", "example": "America/Los_Angeles" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this campaign. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a campaign", "operationId": "Campaign_delete", "description": "Deletes this campaign. Any scheduled messages will be cancelled.", "tags": [ "Campaign" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Campaign" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Get campaign by ID", "operationId": "Project_getCampaignById", "description": "Retrieves the campaign with the given ID.", "tags": [ "Campaign" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the campaign" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/campaigns/{id}/send": { "post": { "summary": "Send or schedule a campaign", "operationId": "Campaign_send", "description": "Sends or schedules this campaign. The campaign must be in the `draft` or `scheduled` status, and must be fully configured (e.g. with a group, route, and message content).\n\n For broadcast campaigns, this will send the campaign immediately if the campaign's `schedule_mode` is `immediate`. If `schedule_mode` is `at_time`, it will schedule the campaign to be sent at the time of the `schedule_time` timestamp.\n\n For relative and anniversary campaigns, this will schedule the campaign according to the configuration in the `items` and `date_variable` properties.", "tags": [ "Campaign" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Campaign" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/campaigns/{id}/unschedule": { "post": { "summary": "Unschedule a campaign", "operationId": "Campaign_unschedule", "description": "Cancels a scheduled campaign, reverting it to the `draft` status. The campaign must be in the `scheduled` or `pending_review` status.", "tags": [ "Campaign" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Campaign" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contact_fields": { "get": { "summary": "Get custom contact fields", "operationId": "Project_getContactFields", "description": "Gets a list of all custom fields defined for contacts in this project. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', 'lookup_key', and 'show_on_conversation'. (Fields are automatically created any time a Contact's 'vars' property is updated.)", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the field" }, "variable": { "type": "string", "description": "Variable name used in the API" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "readonly": { "type": "boolean", "description": "Whether the field is read-only" }, "lookup_key": { "type": "boolean", "description": "Whether the field is a lookup key" }, "show_on_conversation": { "type": "boolean", "description": "Whether to show field on Conversations tab" }, "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Option value stored in the database" }, "label": { "type": "string", "description": "Option label displayed to users" } } }, "description": "For select or radio fields, the list of options" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update custom contact fields", "operationId": "Project_updateContactFields", "description": "Updates metadata for one or more custom contact fields. Only the specified fields are updated; other fields are not affected.\n\n To delete a field, include an object with the `variable` and `delete` properties set (e.g. `{\"variable\": \"my_field\", \"delete\": true}`). Deleting a field will also clear the corresponding variable on all contacts in the project.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string", "description": "Variable name of the field" }, "name": { "type": "string", "description": "Display name for the field" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "readonly": { "type": "boolean", "description": "Whether the field is read-only" }, "lookup_key": { "type": "boolean", "description": "Whether the field is a lookup key" }, "show_on_conversation": { "type": "boolean", "description": "Whether to show field on Conversations tab" }, "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Option value stored in the database" }, "label": { "type": "string", "description": "Option label displayed to users" } } }, "description": "For select or radio fields, the list of options" }, "delete": { "type": "boolean", "description": "Set to true to delete this field. Other properties besides `variable` are ignored when deleting." } }, "required": [ "variable" ] }, "description": "Array of up to 100 objects describing the fields to create, update, or delete. Each object must contain a `variable` property. Only the properties provided for each field will be updated." } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the field" }, "variable": { "type": "string", "description": "Variable name used in the API" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "readonly": { "type": "boolean", "description": "Whether the field is read-only" }, "lookup_key": { "type": "boolean", "description": "Whether the field is a lookup key" }, "show_on_conversation": { "type": "boolean", "description": "Whether to show field on Conversations tab" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contact_stats": { "get": { "summary": "Get historical contact statistics", "operationId": "Project_getContactStats", "description": "Retrieves statistics about the number of contacts in the project (total or in particular groups) over a date range. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include the current number of contacts.\n\n To get historical statistics for the number of contacts matching a filter, use project.createGroup to create a dynamic group for each filter you want to track. However, the statistics will only be available for dates after the dynamic group was created.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "Start date of contact statistics, in YYYY-MM-DD format", "required": true, "example": "2022-01-01" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "End date of contact statistics (inclusive), in YYYY-MM-DD format", "required": true, "example": "2022-12-31" }, { "name": "rollup", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "year" ], "default": "day" }, "description": "Date interval to group by", "example": "month" }, { "name": "cumulative", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "If true, each interval contains the total number of contacts at the end of the interval; if false, each interval contains the change in the number of contacts during the interval." }, { "name": "series", "in": "query", "schema": { "type": "string", "default": "total" }, "style": "form", "explode": false, "description": "Comma separated list of up to 10 data series to return, corresponding to the keys of the `values` object in the response. Each item is either `total` (the total number of contacts in the project) or a group ID (the number of contacts in that group).", "example": "total,CGb0b7201b222fa609" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "intervals": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "integer", "description": "UNIX timestamp of the start of the interval" }, "end_time": { "type": "integer", "description": "UNIX timestamp of the end of the interval, exclusive" }, "start_date": { "type": "string", "description": "Date of the start of the interval in YYYY-MM-DD format" }, "end_date": { "type": "string", "description": "Date of the end of the interval in YYYY-MM-DD format, inclusive" }, "values": { "type": "object", "additionalProperties": true, "description": "Number of contacts for each requested series, with the key `total` for the total number of contacts in the project, and group IDs as keys for the number of contacts in each requested group" } } }, "description": "List of objects representing each date interval." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contacts": { "post": { "summary": "Create, update, or retrieve a contact", "operationId": "Project_getOrCreateContact", "description": "Retrieves OR creates and possibly updates a contact by name or phone number.\n\n 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.\n\n If no existing contact is found, a new contact will be created.\n\n 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`).", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact", "example": "John Smith" }, "phone_number": { "type": "string", "description": "Phone number of the contact", "example": "5550123" }, "lookup_key": { "type": "string", "description": "The field used to search for a matching contact, or 'none' to always create a new contact. To search by a custom variable, precede the variable name with 'vars.'.", "enum": [ "phone_number", "name", "id", "vars.variable_name", "none" ], "default": "phone_number" }, "send_blocked": { "type": "boolean", "description": "True if Telerivet is blocked from sending messages to this contact" }, "default_route_id": { "type": "string", "description": "ID of the route to use by default to send messages to this contact" }, "add_group_ids": { "type": "string", "description": "ID of one or more groups to add this contact as a member (max 20)" }, "id": { "type": "string", "description": "ID of an existing contact (only used if `lookup_key` is 'id')" }, "remove_group_ids": { "type": "string", "description": "ID of one or more groups to remove this contact as a member (max 20)" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables and values to update on the contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Query contacts", "operationId": "Project_queryContacts", "description": "Queries contacts within the given project.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "group_id", "in": "query", "schema": { "type": "string", "description": "ID of Group" }, "description": "Filter contacts within a group" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter contacts by name" }, { "name": "phone_number", "in": "query", "schema": { "type": "string" }, "description": "Filter contacts by phone number" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by time created" }, { "name": "last_message_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by last time a message was sent or received" }, { "name": "last_incoming_message_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by last time a message was received" }, { "name": "last_outgoing_message_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by last time a message was sent" }, { "name": "incoming_message_count", "in": "query", "schema": { "type": "integer" }, "description": "Filter contacts by number of messages received from the contact" }, { "name": "outgoing_message_count", "in": "query", "schema": { "type": "integer" }, "description": "Filter contacts by number of messages sent to the contact" }, { "name": "send_blocked", "in": "query", "schema": { "type": "boolean" }, "description": "Filter contacts by blocked status" }, { "name": "vars", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Filter contacts by value of a custom variable (e.g. vars[email], vars[foo], etc.)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name", "phone_number", "last_message_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contacts/{id}": { "post": { "summary": "Update contact details", "operationId": "Contact_save", "description": "Updates writable fields on the given contact", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the contact", "example": "John Smith" }, "phone_number": { "type": "string", "description": "Phone number of the contact", "example": "+16505550123" }, "send_blocked": { "type": "boolean", "description": "True if Telerivet is blocked from sending messages to this contact", "example": false }, "conversation_status": { "type": "string", "description": "Current status of the conversation with this contact", "enum": [ "closed", "active", "handled" ], "example": "active" }, "default_route_id": { "type": "string", "description": "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)" }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a contact", "operationId": "Contact_delete", "description": "Deletes this contact.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Get contact by ID", "operationId": "Project_getContactById", "description": "Retrieves the contact with the given ID.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the contact" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contacts/{id}/groups": { "get": { "summary": "Query groups for a contact", "operationId": "Contact_queryGroups", "description": "Queries groups for which this contact is a member.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter groups by name" }, { "name": "dynamic", "in": "query", "schema": { "type": "boolean" }, "description": "Filter groups by dynamic/non-dynamic" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contacts/{id}/messages": { "get": { "summary": "Query messages sent or received by a contact", "operationId": "Contact_queryMessages", "description": "Queries messages sent or received by this contact.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "description": "Filter messages by direction", "example": "incoming" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter messages by message_type", "example": "sms" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "phone", "provider", "web", "api", "service", "webhook", "scheduled", "integration", "mcp" ] }, "description": "Filter messages by source" }, { "name": "starred", "in": "query", "schema": { "type": "boolean" }, "description": "Filter messages by starred/unstarred" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ignored", "processing", "received", "sent", "queued", "failed", "failed_queued", "cancelled", "delivered", "not_delivered", "read" ] }, "description": "Filter messages by status" }, { "name": "time_created[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created on or after a particular time" }, { "name": "time_created[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created before a particular time" }, { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Filter messages by ID from an external provider" }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "description": "ID of Contact" }, "description": "ID of the contact who sent/received the message" }, { "name": "phone_id", "in": "query", "schema": { "type": "string", "description": "ID of Phone" }, "description": "ID of the phone (basic route) that sent/received the message" }, { "name": "broadcast_id", "in": "query", "schema": { "type": "string", "description": "ID of Broadcast" }, "description": "ID of the broadcast containing the message" }, { "name": "scheduled_id", "in": "query", "schema": { "type": "string", "description": "ID of ScheduledMessage" }, "description": "ID of the scheduled message that created this message" }, { "name": "group_id", "in": "query", "schema": { "type": "string", "description": "ID of Group" }, "description": "Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contacts/{id}/rows": { "get": { "summary": "Query data rows for a contact", "operationId": "Contact_queryDataRows", "description": "Queries data rows associated with this contact (in any data table).", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter data rows by the time they were created" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataRow" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contacts/{id}/scheduled": { "get": { "summary": "Query scheduled messages for a contact", "operationId": "Contact_queryScheduledMessages", "description": "Queries messages scheduled to this contact (not including messages scheduled to groups that this contact is a member of)", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter scheduled messages by message_type", "example": "sms" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled messages by time_created" }, { "name": "next_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled messages by next_time" }, { "name": "relative_scheduled_id", "in": "query", "schema": { "type": "string", "description": "ID of RelativeScheduledMessage" }, "description": "Filter scheduled messages created for a relative scheduled message" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "next_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledMessage" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/contacts/{id}/states": { "get": { "summary": "Query service states for a contact", "operationId": "Contact_queryServiceStates", "description": "Queries this contact's current states for any service", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Filter states by id", "example": "q1" }, { "name": "vars", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Filter states by value of a custom variable (e.g. vars[email], vars[foo], etc.)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactServiceState" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/create_group": { "post": { "summary": "Create a group", "operationId": "Project_createGroup", "description": "Creates a new group.\n\n If the `filters` parameter is provided, the group will be a dynamic group whose members are determined by the filter conditions. Otherwise, it will be a normal group, initially empty, with the ability to manually add members via contact.addToGroup and remove members via contact.removeFromGroup.\n\n Dynamic group filter conditions can later be updated via the `filters` property of the Group object; a group cannot be converted between a normal group and a dynamic group after it is created.", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the group (must be unique within the project)", "example": "Subscribers" }, "filters": { "type": "object", "additionalProperties": true, "description": "Key-value pairs of conditions that contacts must match to be members of a dynamic group. To filter by a custom variable, precede the variable name with 'vars.' (conditions on custom variables may also be provided as a nested object under a `vars` key, e.g. `{\"vars\": {\"city\": \"Manila\"}}`); other supported keys are `id`, `name`, `phone_number`, `time_created`, `time_updated`, `incoming_message_count`, `outgoing_message_count`, `last_incoming_message_time`, `last_outgoing_message_time`, `conversation_status`, `send_blocked`, `group` (ID of a normal group whose members should be included), `not_group` (ID of a normal group whose members should be excluded), and `q` (full-text search query matching contacts like the search box in the web app). Each value is either a value to match exactly, or an object with an operator such as `ne`, `prefix`, `gte`, `lt`, `exists`, or `not_exists` as the key (e.g. `{\"gte\": 10}`)." }, "allow_sending": { "type": "boolean", "description": "True if messages can be sent to this group, false otherwise.", "default": true }, "add_time_variable": { "type": "string", "description": "Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable.", "example": "subscription_time" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables and values to set for this group. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/data_table_stats": { "get": { "summary": "Get historical data table statistics", "operationId": "Project_getDataTableStats", "description": "Retrieves statistics about the number of rows in particular data tables or data table views over a date range. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include the current number of rows.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "Start date of data table statistics, in YYYY-MM-DD format", "required": true, "example": "2022-01-01" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "End date of data table statistics (inclusive), in YYYY-MM-DD format", "required": true, "example": "2022-12-31" }, { "name": "rollup", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "year" ], "default": "day" }, "description": "Date interval to group by", "example": "month" }, { "name": "cumulative", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "If true, each interval contains the number of rows in each data table at the end of the interval; if false, each interval contains the change in the number of rows during the interval." }, { "name": "series", "in": "query", "schema": { "type": "string" }, "style": "form", "explode": false, "description": "Comma separated list of up to 10 data table IDs and/or data table view IDs, corresponding to the keys of the `values` object in the response.", "required": true, "example": "DTf9f77c9ba69cce50" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "intervals": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "integer", "description": "UNIX timestamp of the start of the interval" }, "end_time": { "type": "integer", "description": "UNIX timestamp of the end of the interval, exclusive" }, "start_date": { "type": "string", "description": "Date of the start of the interval in YYYY-MM-DD format" }, "end_date": { "type": "string", "description": "Date of the end of the interval in YYYY-MM-DD format, inclusive" }, "values": { "type": "object", "additionalProperties": true, "description": "Number of rows in each requested data table or view, with table/view IDs as keys" } } }, "description": "List of objects representing each date interval." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/files": { "get": { "summary": "Query stored files", "operationId": "Project_queryFiles", "description": "Queries files stored within the given project.", "tags": [ "StoredFile" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "filename", "in": "query", "schema": { "type": "string" }, "description": "Filter files by filename" }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "Filter files by MIME type. A type ending in `/*` matches any subtype (e.g. `image/*`).", "example": "image/jpeg" }, { "name": "category", "in": "query", "schema": { "type": "string", "enum": [ "outgoing_media", "incoming_media", "call_audio", "test_recording", "script_module", "icon" ] }, "description": "Filter files by category" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "upload", "recording", "message", "api" ] }, "description": "Filter files by how they were created" }, { "name": "size", "in": "query", "schema": { "type": "integer" }, "description": "Filter files by size in bytes" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter files by time_created" }, { "name": "message_id", "in": "query", "schema": { "type": "string", "description": "ID of Message" }, "description": "Filter files associated with a particular message" }, { "name": "sha256", "in": "query", "schema": { "type": "string" }, "description": "Filter files by the SHA-256 hash of the file content (lowercase hex), e.g. to check whether a particular file has already been uploaded" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "filename", "size", "time_created" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/StoredFile" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Upload a file", "operationId": "Project_uploadFile", "description": "Uploads a file to be stored by Telerivet.\n\n After uploading a file, it can be attached to an outgoing message by passing its ID as a `file_id` item in the `media` parameter of project.sendMessage, project.sendBroadcast, or project.sendMulti. This makes it possible to upload a media file once and attach it to many messages, instead of including the file content in every API request.\n\n The file content is provided inline via the `data` parameter, encoded via Base64, with a maximum decoded file size of 5 MB. Image, video, audio, PDF, and vCard files are supported.\n\n Files are deduplicated by content: if a file previously uploaded via the API in the same project has the same content and MIME type, the existing stored file is returned instead of creating a duplicate.", "tags": [ "StoredFile" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "Base64-encoded file content (max 5 MB decoded). Alternatively, a Base64 data URI such as `data:image/jpeg;base64,...`, in which case the `type` parameter may be omitted." }, "filename": { "type": "string", "description": "Filename of the stored file. If not provided, the filename is generated automatically.", "example": "image.jpg" }, "type": { "type": "string", "description": "MIME type of the file, e.g. `image/jpeg`. If `data` is a data URI, the type may be omitted, but must match the MIME type of the data URI if provided.", "example": "image/jpeg" }, "description": { "type": "string", "description": "Description of the file" } }, "required": [ "data" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredFile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/files/{id}": { "get": { "summary": "Get stored file by ID", "operationId": "Project_getFileById", "description": "Retrieves the stored file with the given ID.", "tags": [ "StoredFile" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the stored file" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredFile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update stored file details", "operationId": "StoredFile_save", "description": "Updates writable fields on the given stored file.", "tags": [ "StoredFile" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the StoredFile" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "filename": { "type": "string", "description": "Filename of the stored file", "example": "image.jpg" }, "description": { "type": "string", "description": "Description of the file" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoredFile" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a stored file", "operationId": "StoredFile_delete", "description": "Deletes this stored file.\n\n A stored file may only be deleted by the user who created it or by a project administrator, and may not be deleted while it is attached to an existing message.", "tags": [ "StoredFile" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the StoredFile" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/groups": { "get": { "summary": "Query groups", "operationId": "Project_queryGroups", "description": "Queries groups within the given project.", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter groups by name" }, { "name": "dynamic", "in": "query", "schema": { "type": "boolean" }, "description": "Filter groups by dynamic/non-dynamic" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Group" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or retrieve a group by name", "operationId": "Project_getOrCreateGroup", "description": "Retrieves or creates a group by name. If a group with that name does not exist, a new normal group will be created, initially empty. (To create a dynamic group, use project.createGroup.)", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the group", "example": "Subscribers" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/groups/{id}": { "get": { "summary": "Get group by ID", "operationId": "Project_getGroupById", "description": "Retrieves the group with the given ID.", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the group" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update group details", "operationId": "Group_save", "description": "Updates writable fields on the given group.", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Group" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the group", "example": "Subscribers" }, "filters": { "type": "object", "additionalProperties": true, "description": "Key-value pairs of conditions that contacts must match to be members of a dynamic group. To filter by a custom variable, precede the variable name with 'vars.' (conditions on custom variables may also be provided as a nested object under a `vars` key, e.g. `{\"vars\": {\"city\": \"Manila\"}}`); other supported keys are `id`, `name`, `phone_number`, `time_created`, `time_updated`, `incoming_message_count`, `outgoing_message_count`, `last_incoming_message_time`, `last_outgoing_message_time`, `conversation_status`, `send_blocked`, `group` (ID of a normal group whose members should be included), `not_group` (ID of a normal group whose members should be excluded), and `q` (full-text search query matching contacts like the search box in the web app). Each value is either a value to match exactly, or an object with an operator such as `ne`, `prefix`, `gte`, `lt`, `exists`, or `not_exists` as the key (e.g. `{\"gte\": 10}`). Null if this is a normal group. Filter conditions can only be updated on dynamic groups." }, "allow_sending": { "type": "boolean", "description": "True if messages can be sent to this group, false otherwise." }, "add_time_variable": { "type": "string", "description": "Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable.", "example": "subscription_time" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this group. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Group" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a group", "operationId": "Group_delete", "description": "Deletes this group (Note: no contacts are deleted.)", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Group" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/groups/{id}/contacts": { "get": { "summary": "Query contacts in a group", "operationId": "Group_queryContacts", "description": "Queries contacts that are members of the given group.", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Group" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter contacts by name" }, { "name": "phone_number", "in": "query", "schema": { "type": "string" }, "description": "Filter contacts by phone number" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by time created" }, { "name": "last_message_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by last time a message was sent or received" }, { "name": "last_incoming_message_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by last time a message was received" }, { "name": "last_outgoing_message_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter contacts by last time a message was sent" }, { "name": "incoming_message_count", "in": "query", "schema": { "type": "integer" }, "description": "Filter contacts by number of messages received from the contact" }, { "name": "outgoing_message_count", "in": "query", "schema": { "type": "integer" }, "description": "Filter contacts by number of messages sent to the contact" }, { "name": "send_blocked", "in": "query", "schema": { "type": "boolean" }, "description": "Filter contacts by blocked status" }, { "name": "vars", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Filter contacts by value of a custom variable (e.g. vars[email], vars[foo], etc.)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name", "phone_number", "last_message_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/groups/{group_id}/contacts/{contact_id}": { "put": { "summary": "Add contact to a group", "operationId": "Contact_addToGroup", "description": "Adds this contact to a group.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Group" }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Remove contact from a group", "operationId": "Contact_removeFromGroup", "description": "Removes this contact from a group.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Group" }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/groups/{id}/scheduled": { "get": { "summary": "Query scheduled messages to a group", "operationId": "Group_queryScheduledMessages", "description": "Queries scheduled messages to the given group.", "tags": [ "Group" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Group" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter scheduled messages by message_type", "example": "sms" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled messages by time_created" }, { "name": "next_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled messages by next_time" }, { "name": "relative_scheduled_id", "in": "query", "schema": { "type": "string", "description": "ID of RelativeScheduledMessage" }, "description": "Filter scheduled messages created for a relative scheduled message" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "next_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledMessage" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/import_contacts": { "post": { "summary": "Import contacts", "operationId": "Project_importContacts", "description": "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.\n\n 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.\n\n If any contact was not found matching the provided `lookup_key`, a new contact will be created.", "tags": [ "Contact" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Contact name" }, "phone_number": { "type": "string", "description": "Contact phone number" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables" }, "send_blocked": { "type": "boolean", "description": "Whether to block outgoing messages to this contact" } } }, "description": "Array of up to 200 objects which may contain the properties `name` (string), `phone_number` (string), `vars` (object), and `send_blocked` (boolean). All properties are optional, unless used as a lookup key; however, either a `name` or `phone_number` property must be provided for new contacts." }, "lookup_key": { "type": "string", "description": "The field used to search for a matching contact, or 'none' to always create a new contact. To search by a custom variable, precede the variable name with 'vars.'.", "enum": [ "phone_number", "id", "vars.variable_name", "none" ], "default": "phone_number" }, "add_group_ids": { "type": "string", "description": "ID of one or more groups to add these contacts as members (max 5)" }, "remove_group_ids": { "type": "string", "description": "ID of one or more groups to remove these contacts as members (max 5)" }, "default_route_id": { "type": "string", "description": "ID of the route to use by default to send messages to these contacts" } }, "required": [ "contacts" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the contact" } }, "required": [ "id" ] }, "description": "List of objects representing each contact, with the same length and order as provided in the `contacts` parameter in the API request. Each object has a string `id` property." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/labels": { "get": { "summary": "Query labels", "operationId": "Project_queryLabels", "description": "Queries labels within the given project.", "tags": [ "Label" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter labels by name" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Label" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or retrieve a label by name", "operationId": "Project_getOrCreateLabel", "description": "Gets or creates a label by name.", "tags": [ "Label" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the label", "example": "Important" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/labels/{id}": { "get": { "summary": "Get label by ID", "operationId": "Project_getLabelById", "description": "Retrieves the label with the given ID.", "tags": [ "Label" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the label" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update label details", "operationId": "Label_save", "description": "Updates writable fields on the given label.", "tags": [ "Label" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Label" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the label", "example": "Important" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this label. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Label" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a label", "operationId": "Label_delete", "description": "Deletes the given label (Note: no messages are deleted.)", "tags": [ "Label" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Label" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/labels/{id}/messages": { "get": { "summary": "Query messages with a label", "operationId": "Label_queryMessages", "description": "Queries messages with the given label.", "tags": [ "Label" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Label" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "description": "Filter messages by direction", "example": "incoming" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter messages by message_type", "example": "sms" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "phone", "provider", "web", "api", "service", "webhook", "scheduled", "integration", "mcp" ] }, "description": "Filter messages by source" }, { "name": "starred", "in": "query", "schema": { "type": "boolean" }, "description": "Filter messages by starred/unstarred" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ignored", "processing", "received", "sent", "queued", "failed", "failed_queued", "cancelled", "delivered", "not_delivered", "read" ] }, "description": "Filter messages by status" }, { "name": "time_created[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created on or after a particular time" }, { "name": "time_created[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created before a particular time" }, { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Filter messages by ID from an external provider" }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "description": "ID of Contact" }, "description": "ID of the contact who sent/received the message" }, { "name": "phone_id", "in": "query", "schema": { "type": "string", "description": "ID of Phone" }, "description": "ID of the phone (basic route) that sent/received the message" }, { "name": "broadcast_id", "in": "query", "schema": { "type": "string", "description": "ID of Broadcast" }, "description": "ID of the broadcast containing the message" }, { "name": "scheduled_id", "in": "query", "schema": { "type": "string", "description": "ID of ScheduledMessage" }, "description": "ID of the scheduled message that created this message" }, { "name": "group_id", "in": "query", "schema": { "type": "string", "description": "ID of Group" }, "description": "Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/labels/{label_id}/messages/{message_id}": { "put": { "summary": "Add a label to a message", "operationId": "Message_addLabel", "description": "Adds a label to the given message.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "label_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Label" }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Remove a label from a message", "operationId": "Message_removeLabel", "description": "Removes a label from the given message.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "label_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Label" }, { "name": "message_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/message_fields": { "get": { "summary": "Get custom message fields", "operationId": "Project_getMessageFields", "description": "Gets a list of all custom fields defined for messages in this project. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', and 'hide_values'. (Fields are automatically created any time a Message's 'vars' property is updated.)", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the field" }, "variable": { "type": "string", "description": "Variable name used in the API" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "hide_values": { "type": "boolean", "description": "Whether to hide field values in the web app" }, "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Option value stored in the database" }, "label": { "type": "string", "description": "Option label displayed to users" } } }, "description": "For select or radio fields, the list of options" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update custom message fields", "operationId": "Project_updateMessageFields", "description": "Updates metadata for one or more custom message fields. Only the specified fields are updated; other fields are not affected.\n\n To delete a field, include an object with the `variable` and `delete` properties set (e.g. `{\"variable\": \"my_field\", \"delete\": true}`). Deleting a field removes the metadata only; values stored on individual messages are not affected.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string", "description": "Variable name of the field" }, "name": { "type": "string", "description": "Display name for the field" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "hide_values": { "type": "boolean", "description": "Whether to hide field values in the web app" }, "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Option value stored in the database" }, "label": { "type": "string", "description": "Option label displayed to users" } } }, "description": "For select, radio, or checkbox fields, the list of options" }, "delete": { "type": "boolean", "description": "Set to true to delete this field. Other properties besides `variable` are ignored when deleting." } }, "required": [ "variable" ] }, "description": "Array of up to 100 objects describing the fields to create, update, or delete. Each object must contain a `variable` property. Only the properties provided for each field will be updated." } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the field" }, "variable": { "type": "string", "description": "Variable name used in the API" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "hide_values": { "type": "boolean", "description": "Whether to hide field values in the web app" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/message_stats": { "get": { "summary": "Get historical message statistics", "operationId": "Project_getMessageStats", "description": "Retrieves statistics about messages sent or received via Telerivet. This endpoint returns historical data that is computed shortly after midnight each day in the project's time zone. If the date range includes the current day, it will include statistics for the current day so far.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "start_date", "in": "query", "schema": { "type": "string" }, "description": "Start date of message statistics, in YYYY-MM-DD format", "required": true, "example": "2022-01-01" }, { "name": "end_date", "in": "query", "schema": { "type": "string" }, "description": "End date of message statistics (inclusive), in YYYY-MM-DD format", "required": true, "example": "2022-12-31" }, { "name": "rollup", "in": "query", "schema": { "type": "string", "enum": [ "day", "week", "month", "year", "all" ], "default": "day" }, "description": "Date interval to group by", "example": "month" }, { "name": "properties", "in": "query", "schema": { "type": "array", "items": { "type": "string", "enum": [ "org_id", "org_name", "org_industry", "project_id", "project_name", "user_id", "user_email", "user_name", "phone_id", "phone_name", "phone_type", "direction", "source", "status", "network_code", "network_name", "message_type", "service_id", "service_name", "simulated", "link" ] } }, "style": "form", "explode": false, "description": "Comma separated list of properties to group by", "example": "phone_name,status,direction" }, { "name": "metrics", "in": "query", "schema": { "type": "string" }, "style": "form", "explode": false, "description": "Comma separated list of metrics to return (summed for each distinct value of the requested properties). Supported metrics are `count` (the number of messages), `num_parts` (the number of SMS parts), `duration` (the total duration of calls, in seconds), and `price.` (the total price of messages priced in the specified ISO 4217 currency, e.g. `price.USD`). Amounts are not converted between currencies: each `price.` metric only includes messages priced in the specified currency.", "required": true, "example": "count,num_parts,price.USD" }, { "name": "filters", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Key-value pairs of properties and corresponding values; the returned statistics will only include messages where the property matches the provided value. Only the following properties are supported for filters: `user_id`, `phone_id`, `direction`, `source`, `status`, `service_id`, `simulated`, `message_type`, `network_code`" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "intervals": { "type": "array", "items": { "type": "object", "properties": { "start_time": { "type": "integer", "description": "UNIX timestamp of the start of the interval" }, "end_time": { "type": "integer", "description": "UNIX timestamp of the end of the interval, exclusive" }, "start_date": { "type": "string", "description": "Date of the start of the interval in YYYY-MM-DD format" }, "end_date": { "type": "string", "description": "Date of the end of the interval in YYYY-MM-DD format, inclusive" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "properties": { "type": "object", "additionalProperties": true, "description": "Key/value pairs for each distinct value of the requested properties" }, "metrics": { "type": "object", "additionalProperties": true, "description": "Key/value pairs for each requested metric" } } }, "description": "Array of groups for each combination of requested property values" } } }, "description": "List of objects representing each date interval containing at least one message matching the filters." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/message_templates": { "get": { "summary": "Query message templates", "operationId": "Project_queryMessageTemplates", "description": "Queries message templates within the given project.", "tags": [ "MessageTemplate" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter templates by name" }, { "name": "waba_id", "in": "query", "schema": { "type": "string" }, "description": "Filter templates by WhatsApp Business Account ID" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageTemplate" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a message template", "operationId": "Project_createMessageTemplate", "description": "Creates a new message template that can be used when composing or scheduling messages.", "tags": [ "MessageTemplate" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the template (max 127 characters)", "example": "Welcome Message" }, "content": { "type": "string", "description": "Content of the message template (max 2000 characters)", "example": "Hello, [[contact.name]]! Welcome to our service." }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the content will be replaced with short links that track clicks. Requires a plan with click tracking enabled.", "default": false }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link." }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "List of attachment objects with file URLs to include with the template" }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending messages with this template. \n\n 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.\n\n For more details, see Route-Specific Parameters." } }, "required": [ "name", "content" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/message_templates/{id}": { "get": { "summary": "Get message template by ID", "operationId": "Project_getMessageTemplateById", "description": "Retrieves the message template with the given ID.", "tags": [ "MessageTemplate" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the message template" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update message template", "operationId": "MessageTemplate_save", "description": "Updates writable fields on the given message template.\n\nNote: Templates synchronized from a WhatsApp Business Account cannot be modified via the API.", "tags": [ "MessageTemplate" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the MessageTemplate" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the template (max 127 characters)", "example": "Welcome Message" }, "content": { "type": "string", "description": "Content of the message template (max 2000 characters)", "example": "Hello, [[contact.name]]! Welcome to our service." }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the content will be replaced with short links that track clicks when the template is used" }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "Custom parameters for short links (only if track_clicks is true)" }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "List of attachment objects with file URLs" }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending messages with this template. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this template. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageTemplate" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a message template", "operationId": "MessageTemplate_delete", "description": "Deletes the message template.\n\nNote: Templates synchronized from a WhatsApp Business Account cannot be deleted via the API.", "tags": [ "MessageTemplate" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the MessageTemplate" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages": { "get": { "summary": "Query messages", "operationId": "Project_queryMessages", "description": "Queries messages within the given project.\n\n Note: To be notified of new incoming messages as they are received, use the [Webhook API](https://telerivet.com/api/webhook).", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "label_id", "in": "query", "schema": { "type": "string", "description": "ID of Label" }, "description": "Filter messages with a label" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "description": "Filter messages by direction", "example": "incoming" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter messages by message_type", "example": "sms" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "phone", "provider", "web", "api", "service", "webhook", "scheduled", "integration", "mcp" ] }, "description": "Filter messages by source" }, { "name": "starred", "in": "query", "schema": { "type": "boolean" }, "description": "Filter messages by starred/unstarred" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ignored", "processing", "received", "sent", "queued", "failed", "failed_queued", "cancelled", "delivered", "not_delivered", "read" ] }, "description": "Filter messages by status" }, { "name": "time_created[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created on or after a particular time" }, { "name": "time_created[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created before a particular time" }, { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Filter messages by ID from an external provider" }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "description": "ID of Contact" }, "description": "ID of the contact who sent/received the message" }, { "name": "phone_id", "in": "query", "schema": { "type": "string", "description": "ID of Phone" }, "description": "ID of the phone (basic route) that sent/received the message" }, { "name": "broadcast_id", "in": "query", "schema": { "type": "string", "description": "ID of Broadcast" }, "description": "ID of the broadcast containing the message" }, { "name": "scheduled_id", "in": "query", "schema": { "type": "string", "description": "ID of ScheduledMessage" }, "description": "ID of the scheduled message that created this message" }, { "name": "group_id", "in": "query", "schema": { "type": "string", "description": "ID of Group" }, "description": "Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages/receive": { "post": { "summary": "Add an incoming message", "operationId": "Project_receiveMessage", "description": "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.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Content of the incoming message", "example": "help" }, "message_type": { "type": "string", "description": "Type of message", "enum": [ "sms", "call", "chat" ], "default": "sms", "example": "sms" }, "from_number": { "type": "string", "description": "Phone number that sent the incoming message", "example": "+16505550193" }, "phone_id": { "type": "string", "description": "ID of the phone (basic route) that received the message" }, "to_number": { "type": "string", "description": "Phone number that the incoming message was sent to", "default": "phone number of the phone that received the message", "example": "+16505551212" }, "simulated": { "type": "boolean", "description": "If true, Telerivet will not send automated replies to actual phones" }, "starred": { "type": "boolean", "description": "True if this message should be starred" }, "label_ids": { "type": "string", "description": "Array of IDs of labels to add to this message (maximum 5)" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables to set for this message" } }, "required": [ "from_number", "phone_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages/send": { "post": { "summary": "Send a message", "operationId": "Project_sendMessage", "description": "Sends one message (SMS, MMS, chat app message, voice call, or USSD request).", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_type": { "type": "string", "description": "Type of message to send. If `text`, will use the default text message type for the selected route.", "enum": [ "text", "sms", "mms", "ussd", "call", "chat", "service" ], "default": "text" }, "content": { "type": "string", "description": "Content of the message to send (if `message_type` is `call`, the text will be spoken during a text-to-speech call)", "example": "hello world" }, "to_number": { "type": "string", "description": "Phone number to send the message to", "example": "+16505550123" }, "contact_id": { "type": "string", "description": "ID of the contact to send the message to" }, "route_id": { "type": "string", "description": "ID of the phone or route to send the message from", "default": "default sender route ID for your project" }, "status_url": { "type": "string", "description": "Webhook callback URL to be notified when message status changes" }, "status_secret": { "type": "string", "description": "POST parameter 'secret' passed to status_url" }, "replace_variables": { "type": "boolean", "description": "Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)", "default": "false" }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs.", "default": "false" }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link in the message. The following parameters are supported:\n\n `domain` (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.\n\n `expiration_sec` (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL.\n If null, the short links will not expire." }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n Use a https:// or http:// URL for media files that are already accessible via the internet.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project." }, "file_id": { "type": "string", "description": "ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required." }, "type": { "type": "string", "description": "MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media. Ignored if file_id is provided." } } }, "description": "Array of media attachments for the text message.\n\n If sending a type of message that doesn't support attachments (e.g. SMS), short links to each media URL will be appended to the end of the content (separated by a new line).\n\n Alternatively, you can use the `media_urls` parameter with an array of URL strings." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "label_ids": { "type": "string", "description": "List of IDs of labels to add to this message" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables to store with the message" }, "priority": { "type": "integer", "description": "Priority of the message. Telerivet will attempt to send messages with higher priority numbers first (for example, so you can prioritize an auto-reply ahead of a bulk message to a large group).", "enum": [ 1, 2 ], "default": 1 }, "simulated": { "type": "boolean", "description": "Set to true to test the Telerivet API without actually sending a message from the route", "default": "false" }, "service_id": { "type": "string", "description": "Service that defines the call flow of the voice call (when `message_type` is `call`)" }, "audio_url": { "type": "string", "description": "The URL of an MP3 file to play when the contact answers the call (when `message_type` is `call`).\n\n If `audio_url` is provided, the text-to-speech voice is not used to say `content`, although you can optionally use `content` to indicate the script for the audio.\n\n For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line." }, "tts_lang": { "type": "string", "description": "The language of the text-to-speech voice (when `message_type` is `call`)", "enum": [ "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" ], "default": "en-US" }, "tts_voice": { "type": "string", "description": "The name of the text-to-speech voice (when message_type=call)", "enum": [ "female", "male" ], "default": "female" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages/{id}": { "post": { "summary": "Update message details", "operationId": "Message_save", "description": "Updates writable fields on the given message", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "starred": { "type": "boolean", "description": "Whether this message is starred in Telerivet", "example": true }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "error_message": { "type": "string", "description": "A description of the error encountered while sending a message. (This field is omitted from the API response if there is no error message.)" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a message", "operationId": "Message_delete", "description": "Deletes this message.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Get message by ID", "operationId": "Project_getMessageById", "description": "Retrieves the message with the given ID.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the message" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages/{id}/cancel": { "post": { "summary": "Cancel sending a message", "operationId": "Message_cancel", "description": "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'.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages/{id}/resend": { "post": { "summary": "Resend a message", "operationId": "Message_resend", "description": "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.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "route_id": { "type": "string", "description": "ID of the phone or route to send the message from", "example": "PN4d246818d0ecd1fa" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Message" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages/{id}/send_read_receipt": { "post": { "summary": "Send a read receipt", "operationId": "Message_sendReadReceipt", "description": "Sends a read receipt for this message. Currently only supported for incoming WhatsApp messages.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/messages/{id}/send_typing_indicator": { "post": { "summary": "Send a typing indicator", "operationId": "Message_sendTypingIndicator", "description": "Sends a typing indicator for this message. Currently only supported for incoming WhatsApp messages.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Message" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/phones": { "get": { "summary": "Query basic routes", "operationId": "Project_queryPhones", "description": "Queries basic routes within the given project.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter phones by name" }, { "name": "phone_number", "in": "query", "schema": { "type": "string" }, "description": "Filter phones by phone number" }, { "name": "last_active_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter phones by last active time" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name", "phone_number" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Phone" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a basic route", "operationId": "Project_createPhone", "description": "Creates a new basic route (phone) with external API credentials.\n\nFor some external API providers, this method automatically updates webhook URLs configured with the external provider so that incoming messages/calls and call status events are routed to Telerivet. In this case, if you have already configured a webhook URL with the external provider, it will be overwritten. For other external API providers, webhook URLs may require manual configuration in order for the route to be fully functional.\n\nNote: This API can only create routes that connect to external gateway APIs using your own account credentials. To add Android phones, WhatsApp routes, or routes with Telerivet-managed billing, use the web app instead.\n\nCredentials are passed via the `external_account_id`, `external_id`, `external_secret`, and `external_config` parameters. The meaning of these parameters for each phone type is as follows:\n\n**Twilio Virtual Number** (`phone_type`: twilio):\n\n- external_id (optional): Twilio phone number SID (starts with 'PN'); looked up by phone_number if not provided\n- external_account_id (required): Twilio Account SID (starts with 'AC')\n- external_secret (required): Twilio Auth Token\n\n**Twilio Messaging Service** (`phone_type`: twilio_messaging_service):\n\n- external_id (required): Twilio messaging service SID (starts with 'MG')\n- external_account_id (required): Twilio Account SID (starts with 'AC')\n- external_secret (required): Twilio Auth Token\n\n**Twilio Shortcode** (`phone_type`: twilio_shortcode):\n\n- external_id (optional): Twilio shortcode SID (starts with 'SC'); looked up by phone_number if not provided\n- external_account_id (required): Twilio Account SID (starts with 'AC')\n- external_secret (required): Twilio Auth Token\n\n**Twilio Caller ID** (`phone_type`: twilio_caller_id):\n\n- external_account_id (required): Twilio Account SID (starts with 'AC')\n- external_secret (required): Twilio Auth Token\n\n**Vonage Virtual Number** (`phone_type`: nexmo):\n\n- external_account_id (required): Vonage API Key\n- external_secret (required): Vonage API Secret\n\n**Vonage Sender ID** (`phone_type`: nexmo_sender_id):\n\n- external_account_id (required): Vonage API Key\n- external_secret (required): Vonage API Secret\n\n**Telesign SMS** (`phone_type`: telesign):\n\n- external_account_id (required): Telesign Customer ID\n- external_secret (required): Telesign API Key\n- external_config.message_type: ARN, MKT, or OTP\n- external_config.sender_type: one_way (default) or two_way\n\n**Infobip SMS** (`phone_type`: infobip):\n\n- external_account_id (required): Infobip username\n- external_secret (required): Infobip API key\n- external_config.sender_type: one_way (default) or two_way\n- external_config.india_dlt_principal_entity_id: India DLT Principal Entity ID (only for India)\n\n**Infobip USSD** (`phone_type`: infobip_ussd):\n\n- No external credentials required\n\n**Africa's Talking SMS** (`phone_type`: africas_talking):\n\n- external_account_id (required): Africa's Talking username\n- external_secret (required): Africa's Talking API key\n- external_config.sender_type: one_way (default) or two_way\n\n**Africa's Talking USSD** (`phone_type`: africas_talking_ussd):\n\n- No external credentials required\n\n**Simulated Phone** (`phone_type`: simulated):\n\n- No external credentials required\n- Messages are simulated locally and not sent to any external provider\n- Useful for testing\n\n#### Webhook URL Setup\n\nSome route types require manual configuration of callback URLs in the external provider's dashboard. When the Phone response includes an `external_setup` object, you will need to configure the webhook URLs in your provider's account settings.\n\nThe following phone types require manual webhook setup:\n\n- `africas_talking`: `message_status_url` (always), `incoming_message_url` (if two_way)\n- `africas_talking_ussd`: `incoming_call_url`\n- `infobip_ussd`: `incoming_call_url`\n- `twilio_messaging_service`: `incoming_message_url`\n- `telesign` (two_way only): `incoming_message_url`\n\nTelerivet automatically configures webhooks for the following phone types as follows:\n\n- `twilio` - automatically updates incoming SMS and voice configuration for the Twilio virtual number associated with the phone_number or external_id parameter\n- `twilio_shortcode` - automatically updates incoming SMS configuration for the Twilio short code associated with the phone_number or external_id parameter\n- `nexmo` - automatically updates incoming SMS and voice configuration for the Vonage virtual number matching the phone_number parameter\n- `infobip` - automatically updates incoming SMS configuration for the Infobip virtual number matching the phone_number parameter or external_id parameter", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the basic route to create", "example": "Example Route" }, "phone_number": { "type": "string", "description": "Phone number or sender ID", "example": "+14155550123" }, "phone_type": { "type": "string", "description": "Type of basic route to create. Supported values: twilio, twilio_messaging_service, twilio_shortcode, twilio_caller_id, nexmo, infobip, africas_talking, africas_talking_ussd, infobip_ussd, telesign, simulated. Other types of basic routes can only be created via the web app.", "example": "twilio" }, "external_account_id": { "type": "string", "description": "Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). See the description above for the meaning of this parameter for each phone type.", "example": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }, "external_id": { "type": "string", "description": "External phone/resource ID within the external API account (if applicable). For `twilio` and `twilio_shortcode` routes, this is optional and will be looked up automatically from the phone_number if not provided." }, "external_secret": { "type": "string", "description": "Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). This value is required when creating a new route but is never returned in API responses. See the description above for the meaning of this parameter for each phone type.", "example": "your_api_secret_here" }, "external_config": { "type": "object", "additionalProperties": true, "description": "Additional configuration settings specific to the phone_type. See the description above for available settings for each phone type." }, "country": { "type": "string", "description": "2-letter country code (ISO 3166-1 alpha-2) where phone is from. This country code is used to automatically convert phone numbers in local format to international format. If not provided, will be set to the organization's country by default.", "example": "US" }, "send_paused": { "type": "boolean", "description": "True if sending messages should initially be paused, false otherwise", "default": false }, "timezone_id": { "type": "string", "description": "A string specifying the time zone used when sending messages; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When not provided, the project's default time zone is used.", "example": "America/Los_Angeles" }, "validate_recipient_numbers": { "type": "boolean", "description": "Set to true to validate recipient phone numbers before sending. Messages to invalid numbers will fail without being sent.", "default": false }, "allowed_recipient_countries": { "type": "array", "items": { "type": "string" }, "description": "Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. If not provided, there is no restriction." }, "send_delay": { "type": "number", "description": "Number of seconds to wait after sending each message, to avoid exceeding carrier rate limits.", "example": 1.5 }, "quiet_mode": { "type": "string", "description": "Controls behavior during quiet hours. Possible values: 'off' (disabled), 'delay' (messages delayed until quiet hours end), 'confirm' (requires manual confirmation; worker-based routes only).", "enum": [ "off", "delay", "confirm" ], "default": "off", "example": "delay" }, "quiet_start": { "type": "string", "description": "Time when quiet hours begin, in HH:MM format (24-hour time). Only applicable when quiet_mode is not 'off'.", "example": "22:00" }, "quiet_end": { "type": "string", "description": "Time when quiet hours end, in HH:MM format (24-hour time). Only applicable when quiet_mode is not 'off'.", "example": "08:00" }, "vars": { "type": "string", "description": "Custom variables and values to set for this basic route" } }, "required": [ "phone_number", "phone_type" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/phones/{id}": { "get": { "summary": "Get basic route by ID", "operationId": "Project_getPhoneById", "description": "Retrieves the basic route with the given ID.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the phone - see " } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update basic route", "operationId": "Phone_save", "description": "Saves any fields or custom variables that have changed for this basic route.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Phone" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the phone", "example": "Android Phone 1" }, "phone_number": { "type": "string", "description": "Phone number or sender ID", "example": "+16505550001" }, "send_paused": { "type": "boolean", "description": "True if sending messages is currently paused, false if the phone can currently send messages", "example": false }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this phone. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "validate_recipient_numbers": { "type": "boolean", "description": "Set to true to check that recipient phone numbers appear to be valid before sending messages. Messages to invalid phone numbers will fail without being sent. Only applies to phones capable of sending messages.", "example": true }, "allowed_recipient_countries": { "type": "array", "items": { "type": "string" }, "description": "Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. When null, there is no restriction on recipient countries." }, "sent_message_limit": { "type": "integer", "description": "Maximum number of messages that can be sent from this phone in a given period. When the sent_message_count reaches this limit, sending is automatically paused. Set to null to disable the limit.", "example": 1000 }, "send_delay": { "type": "number", "description": "Number of seconds to wait after sending each message from this phone, to avoid exceeding carrier rate limits.", "example": 1.5 }, "timezone_id": { "type": "string", "description": "A string specifying the time zone that will be used when implementing quiet hours or estimating send times; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When null, the project's default time zone is used.", "example": "America/Los_Angeles" }, "quiet_mode": { "type": "string", "description": "Controls behavior during quiet hours (see quiet_start/quiet_end). Possible values are 'off' (quiet hours disabled), 'delay' (messages are delayed until quiet hours end), or 'confirm' (requires manual confirmation to send during quiet hours).", "enum": [ "off", "delay", "confirm" ], "example": "delay" }, "quiet_start": { "type": "string", "description": "Time of day when quiet hours begin, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.", "example": "22:00" }, "quiet_end": { "type": "string", "description": "Time of day when quiet hours end, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.", "example": "08:00" }, "external_account_id": { "type": "string", "description": "Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). Only present for routes that support external API configuration. See createPhone for the meaning of this field for each phone type." }, "external_id": { "type": "string", "description": "External phone/resource ID within the external API account (if applicable). Only present for routes that support external API configuration." }, "external_config": { "type": "object", "additionalProperties": true, "description": "Additional configuration settings specific to the phone_type. Only present for routes that support external API configuration. See createPhone for available settings for each phone type." }, "external_secret": { "type": "string", "description": "Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). Only applicable for routes that support external API configuration. Write-only; not returned by the API when retrieving a phone." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Phone" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/phones/{id}/messages": { "get": { "summary": "Query messages for a basic route", "operationId": "Phone_queryMessages", "description": "Queries messages sent or received by this basic route.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Phone" }, { "name": "direction", "in": "query", "schema": { "type": "string", "enum": [ "incoming", "outgoing" ] }, "description": "Filter messages by direction", "example": "incoming" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter messages by message_type", "example": "sms" }, { "name": "source", "in": "query", "schema": { "type": "string", "enum": [ "phone", "provider", "web", "api", "service", "webhook", "scheduled", "integration", "mcp" ] }, "description": "Filter messages by source" }, { "name": "starred", "in": "query", "schema": { "type": "boolean" }, "description": "Filter messages by starred/unstarred" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "ignored", "processing", "received", "sent", "queued", "failed", "failed_queued", "cancelled", "delivered", "not_delivered", "read" ] }, "description": "Filter messages by status" }, { "name": "time_created[min]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created on or after a particular time" }, { "name": "time_created[max]", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter messages created before a particular time" }, { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Filter messages by ID from an external provider" }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "description": "ID of Contact" }, "description": "ID of the contact who sent/received the message" }, { "name": "phone_id", "in": "query", "schema": { "type": "string", "description": "ID of Phone" }, "description": "ID of the phone (basic route) that sent/received the message" }, { "name": "broadcast_id", "in": "query", "schema": { "type": "string", "description": "ID of Broadcast" }, "description": "ID of the broadcast containing the message" }, { "name": "scheduled_id", "in": "query", "schema": { "type": "string", "description": "ID of ScheduledMessage" }, "description": "ID of the scheduled message that created this message" }, { "name": "group_id", "in": "query", "schema": { "type": "string", "description": "ID of Group" }, "description": "Filter messages sent or received by contacts in a particular group. The group must be a normal group, not a dynamic group." }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/phones/{id}/reset_sent_message_count": { "post": { "summary": "Reset sent message count", "operationId": "Phone_resetSentMessageCount", "description": "Resets this route's sent_message_count to 0 and updates sent_message_epoch to the current time. If sending was automatically paused because the previous count reached the limit, sending will be resumed.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Phone" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/relative_scheduled": { "post": { "summary": "Create relative scheduled message", "operationId": "Project_createRelativeScheduledMessage", "description": "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.\n\n Telerivet will automatically create a ScheduledMessage for each contact matching a RelativeScheduledMessage.\n\n 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.\n\n 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.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_type": { "type": "string", "description": "Type of message to send", "enum": { "0": "text", "1": "sms", "2": "mms", "4": "call", "5": "chat", "6": "service" }, "default": "text" }, "content": { "type": "string", "description": "Content of the message to schedule", "example": "Hi [[contact.name]], just following up!" }, "group_id": { "type": "string", "description": "ID of the group to send the message to. Dynamic groups are not supported.", "example": "GC123123123123123123" }, "to_number": { "type": "string", "description": "Phone number to send the message to" }, "contact_id": { "type": "string", "description": "ID of the contact to send the message to" }, "time_of_day": { "type": "string", "description": "Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23)", "example": "15:07" }, "timezone_id": { "type": "string", "description": "TZ database timezone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "default": "project default timezone" }, "date_variable": { "type": "string", "description": "Custom contact variable storing date or date/time values relative to which messages will be scheduled.", "example": "date" }, "offset_scale": { "type": "string", "description": "The type of interval 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 (I=minutes, D=day, W=week, M=month, Y=year)", "enum": [ "I", "D", "W", "M", "Y" ], "default": "D", "example": "D" }, "offset_count": { "type": "integer", "description": "The number of days/weeks/months/years to adjust the date of the scheduled message relative relative to the date stored in the custom contact variable identified by the date_variable parameter. May be positive, negative, or zero.", "default": 0, "example": 3 }, "rrule": { "type": "string", "description": "A recurrence rule describing the how the schedule repeats, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see . (UNTIL is ignored; use end_time parameter instead).", "default": "COUNT=1 (one-time scheduled message, does not repeat)", "example": "FREQ=MONTHLY" }, "route_id": { "type": "string", "description": "ID of the phone or route to send the message from", "default": "default sender route ID" }, "service_id": { "type": "string", "description": "Service to invoke for each recipient (when `message_type` is `call` or `service`)" }, "audio_url": { "type": "string", "description": "The URL of an MP3 file to play when the contact answers the call (when `message_type` is `call`).\n\n If `audio_url` is provided, the text-to-speech voice is not used to say `content`, although you can optionally use `content` to indicate the script for the audio.\n\n For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line." }, "tts_lang": { "type": "string", "description": "The language of the text-to-speech voice (when `message_type` is `call`)", "enum": [ "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" ], "default": "en-US" }, "tts_voice": { "type": "string", "description": "The name of the text-to-speech voice (when message_type=call)", "enum": [ "female", "male" ], "default": "female" }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs.", "default": "false" }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link in the message. The following parameters are supported:\n\n `domain` (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.\n\n `expiration_sec` (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL.\n If null, the short links will not expire." }, "replace_variables": { "type": "boolean", "description": "Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)", "default": "false", "example": true }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n Use a https:// or http:// URL for media files that are already accessible via the internet.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project." }, "file_id": { "type": "string", "description": "ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required." }, "type": { "type": "string", "description": "MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media. Ignored if file_id is provided." } } }, "description": "Array of media attachments for the text message.\n\n If sending a type of message that doesn't support attachments (e.g. SMS), short links to each media URL will be appended to the end of the content (separated by a new line).\n\n Alternatively, you can use the `media_urls` parameter with an array of URL strings." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending the message. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "label_ids": { "type": "string", "description": "Array of IDs of labels to add to the sent messages (maximum 5). Does not apply when `message_type`=`service`, since the labels are determined by the service itself." }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)" }, "end_time_offset": { "type": "integer", "description": "Number of seconds from now until the recurring message will stop" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables to set for this relative scheduled message, which will be copied to each message sent from this scheduled message" } }, "required": [ "time_of_day", "date_variable" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelativeScheduledMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Query relative scheduled messages", "operationId": "Project_queryRelativeScheduledMessages", "description": "Queries relative scheduled messages within the given project.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter relative scheduled messages by message_type", "example": "sms" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter relative scheduled messages by time_created" }, { "name": "group_id", "in": "query", "schema": { "type": "string", "description": "ID of Group" }, "description": "Filter relative scheduled messages sent to a group" }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "description": "ID of Contact" }, "description": "Filter relative scheduled messages sent to an individual contact" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RelativeScheduledMessage" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/relative_scheduled/{id}": { "post": { "summary": "Update relative scheduled message", "operationId": "RelativeScheduledMessage_save", "description": "Updates writable fields on the given relative scheduled message.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the RelativeScheduledMessage" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Text content of the relative scheduled message", "example": "hello world!" }, "time_of_day": { "type": "string", "description": "Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23)", "example": "15:07" }, "date_variable": { "type": "string", "description": "Custom contact variable storing date or date/time values relative to which messages will be scheduled.", "example": "date" }, "offset_scale": { "type": "string", "description": "The type of interval 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 (I=minutes, D=day, W=week, M=month, Y=year)", "enum": [ "I", "D", "W", "M", "Y" ], "example": "D" }, "offset_count": { "type": "integer", "description": "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.", "example": 3 }, "rrule": { "type": "string", "description": "Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see [RFC2445](https://tools.ietf.org/html/rfc2445#section-4.3.10).", "example": "COUNT=1" }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which recurring messages will stop (not applicable to non-recurring scheduled messages)" }, "timezone_id": { "type": "string", "description": "Timezone ID used to compute times for recurring messages; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "group_id": { "type": "string", "description": "ID of the group to send the message to (null if the recipient is an individual contact)" }, "contact_id": { "type": "string", "description": "ID of the contact to send the message to (null if the recipient is a group)" }, "to_number": { "type": "string", "description": "Phone number to send the message to (null if the recipient is a group)" }, "route_id": { "type": "string", "description": "ID of the phone or route the message will be sent from", "example": "PN4d246818d0ecd1fa" }, "service_id": { "type": "string", "description": "The service associated with this message (for voice calls, the service defines the call flow)", "example": "SV3d246818d0e3d1fb" }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call" }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice", "enum": [ "female", "male" ] }, "replace_variables": { "type": "boolean", "description": "Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise", "example": false }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments for the text message. This property is undefined for messages that do not contain media files." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending the message. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "label_ids": { "type": "string", "description": "IDs of labels to add to the Message" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelativeScheduledMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete relative scheduled message", "operationId": "RelativeScheduledMessage_delete", "description": "Deletes this relative scheduled message and any associated scheduled messages.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the RelativeScheduledMessage" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Get relative scheduled message by ID", "operationId": "Project_getRelativeScheduledMessageById", "description": "Retrieves the scheduled message with the given ID.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the relative scheduled message" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelativeScheduledMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/route_list": { "get": { "summary": "Get route list", "operationId": "Project_getRouteList", "description": "Returns a list of all available routes for sending messages in a project, including both basic routes (phones) and custom routes.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the route or phone" }, "name": { "type": "string", "description": "Display name" }, "phone_number": { "type": "string", "description": "Phone number (only for basic routes)" }, "phone_type": { "type": "string", "description": "Phone type (only for basic routes)" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/routes": { "get": { "summary": "Query custom routes", "operationId": "Project_queryRoutes", "description": "Queries custom routes that can be used to send messages (not including Phones).", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter routes by name" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Route" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a custom route", "operationId": "Project_createRoute", "description": "Creates a new custom route that can be used to send messages via one or more basic routes (phones).\n\nThe `actions` array defines the routing rules.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the custom route to create", "example": "My Custom Route" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingAction" }, "description": "Array of routing action objects. Allowed action types: `use_phone` (select basic routes to send messages), `condition` (conditionally execute actions based on criteria)." }, "vars": { "type": "string", "description": "Custom variables and values to set for this route" } }, "required": [ "name", "actions" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/routes/{id}": { "get": { "summary": "Get custom route by ID", "operationId": "Project_getRouteById", "description": "Gets a custom route by ID", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the route" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update custom route", "operationId": "Route_save", "description": "Saves any fields, custom variables, or routing actions that have changed for this custom route.", "tags": [ "Phone" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Route" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the route", "example": "Custom Route" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this route. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingAction" }, "description": "Array of routing action objects. Allowed action types: `use_phone`, `condition`." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Route" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/scheduled": { "post": { "summary": "Schedule a message", "operationId": "Project_scheduleMessage", "description": "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.\n\n Only one of the parameters group_id, to_number, and contact_id should be provided.\n\n With `message_type`=`service`, schedules an automated service (such as a poll) to be invoked for a group or an individual contact. Any service that can be triggered for a contact can be scheduled via this method, whether or not the service actually sends a message.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_type": { "type": "string", "description": "Type of message to send", "enum": [ "text", "sms", "mms", "ussd", "call", "chat", "service" ], "default": "text" }, "content": { "type": "string", "description": "Content of the message to schedule", "example": "Reminder!" }, "group_id": { "type": "string", "description": "ID of the group to send the message to" }, "to_number": { "type": "string", "description": "Phone number to send the message to", "example": "+16505550234" }, "contact_id": { "type": "string", "description": "ID of the contact to send the message to" }, "start_time": { "type": "integer", "format": "unix-timestamp", "description": "The time that the message will be sent (or first sent for recurring messages)" }, "start_time_offset": { "type": "integer", "description": "Number of seconds from now until the message is sent", "example": 86400 }, "rrule": { "type": "string", "description": "A recurrence rule describing the how the schedule repeats, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see . (UNTIL is ignored; use end_time parameter instead).", "default": "COUNT=1 (one-time scheduled message, does not repeat)" }, "route_id": { "type": "string", "description": "ID of the phone or route to send the message from", "default": "default sender route ID" }, "service_id": { "type": "string", "description": "Service to invoke for each recipient (when `message_type` is `call` or `service`)" }, "audio_url": { "type": "string", "description": "The URL of an MP3 file to play when the contact answers the call (when `message_type` is `call`).\n\n If `audio_url` is provided, the text-to-speech voice is not used to say `content`, although you can optionally use `content` to indicate the script for the audio.\n\n For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line." }, "tts_lang": { "type": "string", "description": "The language of the text-to-speech voice (when `message_type` is `call`)", "enum": [ "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" ], "default": "en-US" }, "tts_voice": { "type": "string", "description": "The name of the text-to-speech voice (when message_type=call)", "enum": [ "female", "male" ], "default": "female" }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs.", "default": "false" }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link in the message. The following parameters are supported:\n\n `domain` (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.\n\n `expiration_sec` (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL.\n If null, the short links will not expire." }, "replace_variables": { "type": "boolean", "description": "Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)", "default": "false" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n Use a https:// or http:// URL for media files that are already accessible via the internet.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project." }, "file_id": { "type": "string", "description": "ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required." }, "type": { "type": "string", "description": "MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media. Ignored if file_id is provided." } } }, "description": "Array of media attachments for the text message.\n\n If sending a type of message that doesn't support attachments (e.g. SMS), short links to each media URL will be appended to the end of the content (separated by a new line).\n\n Alternatively, you can use the `media_urls` parameter with an array of URL strings." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending the message. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "label_ids": { "type": "string", "description": "Array of IDs of labels to add to the sent messages (maximum 5). Does not apply when `message_type`=`service`, since the labels are determined by the service itself." }, "timezone_id": { "type": "string", "description": "TZ database timezone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "default": "project default timezone" }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)" }, "end_time_offset": { "type": "integer", "description": "Number of seconds from now until the recurring message will stop" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables to set for this scheduled message, which will be copied to each message sent from this scheduled message" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Query scheduled messages", "operationId": "Project_queryScheduledMessages", "description": "Queries scheduled messages within the given project.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "message_type", "in": "query", "schema": { "type": "string", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ] }, "description": "Filter scheduled messages by message_type", "example": "sms" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled messages by time_created" }, { "name": "next_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled messages by next_time" }, { "name": "relative_scheduled_id", "in": "query", "schema": { "type": "string", "description": "ID of RelativeScheduledMessage" }, "description": "Filter scheduled messages created for a relative scheduled message" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "next_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledMessage" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/scheduled/{id}": { "post": { "summary": "Update scheduled message", "operationId": "ScheduledMessage_save", "description": "Updates writable fields on the given scheduled message.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the ScheduledMessage" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "description": "Text content of the scheduled message", "example": "hello world!" }, "rrule": { "type": "string", "description": "Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see [RFC2445](https://tools.ietf.org/html/rfc2445#section-4.3.10).", "example": "COUNT=1" }, "timezone_id": { "type": "string", "description": "Timezone ID used to compute times for recurring messages; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "group_id": { "type": "string", "description": "ID of the group to send the message to (null if the recipient is an individual contact, or if there are multiple recipients)" }, "contact_id": { "type": "string", "description": "ID of the contact to send the message to (null if the recipient is a group, or if there are multiple recipients)" }, "to_number": { "type": "string", "description": "Phone number to send the message to (null if the recipient is a group, or if there are multiple recipients)" }, "route_id": { "type": "string", "description": "ID of the phone or route the message will be sent from", "example": "PN4d246818d0ecd1fa" }, "service_id": { "type": "string", "description": "The service associated with this message (for voice calls, the service defines the call flow)", "example": "SV3d246818d0e3d1fb" }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call" }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice", "enum": [ "female", "male" ] }, "start_time": { "type": "integer", "format": "unix-timestamp", "description": "The time that the message will be sent (or first sent for recurring messages)", "example": 1395617516 }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)" }, "replace_variables": { "type": "boolean", "description": "Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise", "example": false }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments for the text message. This property is undefined for messages that do not contain media files." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending the message. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "label_ids": { "type": "string", "description": "IDs of labels to add to the Message" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Cancel a scheduled message", "operationId": "ScheduledMessage_delete", "description": "Cancels this scheduled message.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the ScheduledMessage" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Get scheduled message by ID", "operationId": "Project_getScheduledMessageById", "description": "Retrieves the scheduled message with the given ID.", "tags": [ "ScheduledMessage" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the scheduled message" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledMessage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/scheduled_services": { "get": { "summary": "Query scheduled services", "operationId": "Project_queryScheduledServices", "description": "Queries scheduled services within the given project.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "service_id", "in": "query", "schema": { "type": "string", "description": "ID of Service" }, "description": "Filter scheduled services by the service ID" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled services by time_created" }, { "name": "next_time", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter scheduled services by next_time" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "next_time" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledService" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Schedule a service", "operationId": "Project_scheduleService", "description": "Schedules a service to be triggered at a specified time.\n\n Only services that can be triggered for the project context and handle the default event can be scheduled. This includes services with types `scheduled_actions`, `scheduled_script`, and other service types that support project-level triggering.\n\n (Note: To schedule services that are triggered for a contact, project.scheduleMessage should be used instead with `message_type`=`service`.)", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "service_id": { "type": "string", "description": "ID of the service to schedule" }, "start_time": { "type": "integer", "format": "unix-timestamp", "description": "The time that the service will be triggered (or first triggered for recurring scheduled services)" }, "start_time_offset": { "type": "integer", "description": "Number of seconds from now to trigger the service" }, "rrule": { "type": "string", "description": "A recurrence rule describing how the schedule repeats, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see . (UNTIL is ignored; use end_time parameter instead).", "default": "COUNT=1 (one-time scheduled service, does not repeat)", "example": "FREQ=DAILY" }, "timezone_id": { "type": "string", "description": "TZ database timezone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "default": "project default timezone" }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which a recurring scheduled service will stop (not applicable to non-recurring scheduled services)" }, "end_time_offset": { "type": "integer", "description": "Number of seconds from now until the recurring scheduled service will stop" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables to store for this scheduled service" } }, "required": [ "service_id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledService" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/scheduled_services/{id}": { "post": { "summary": "Update scheduled service", "operationId": "ScheduledService_save", "description": "Updates the given scheduled service.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the ScheduledService" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "rrule": { "type": "string", "description": "Recurrence rule for recurring scheduled services, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see [RFC2445](https://tools.ietf.org/html/rfc2445#section-4.3.10).", "example": "COUNT=1" }, "timezone_id": { "type": "string", "description": "Timezone ID used to compute times for recurring scheduled services; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "start_time": { "type": "integer", "format": "unix-timestamp", "description": "The time that the service will be triggered (or first triggered for recurring scheduled services)", "example": 1395617516 }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which a recurring scheduled service will stop (not applicable to non-recurring scheduled services)" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this scheduled service. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledService" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a scheduled service", "operationId": "ScheduledService_delete", "description": "Cancels this scheduled service.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the ScheduledService" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Get scheduled service by ID", "operationId": "Project_getScheduledServiceById", "description": "Retrieves the scheduled service with the given ID.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the scheduled service" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScheduledService" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/send_broadcast": { "post": { "summary": "Send a message to a group", "operationId": "Project_sendBroadcast", "description": "Sends a text message (optionally with mail-merge templates) or voice call to a group or a list of up to 500 phone numbers.\n\n 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.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_type": { "type": "string", "description": "Type of message to send. If `text`, will use the default text message type for the selected route.", "enum": { "0": "text", "1": "sms", "2": "mms", "4": "call", "5": "chat", "6": "service" }, "default": "text" }, "content": { "type": "string", "description": "Content of the message to send", "example": "hello [[contact.name]]!" }, "group_id": { "type": "string", "description": "ID of the group to send the message to" }, "to_numbers": { "type": "array", "items": { "type": "string" }, "description": "List of up to 500 phone numbers to send the message to" }, "route_id": { "type": "string", "description": "ID of the phone or route to send the message from", "default": "default sender route ID" }, "title": { "type": "string", "description": "Title of the broadcast. If a title is not provided, a title will automatically be generated from the recipient group name or phone numbers." }, "status_url": { "type": "string", "description": "Webhook callback URL to be notified when message status changes", "example": "https://example.com/sms_status.php" }, "status_secret": { "type": "string", "description": "POST parameter 'secret' passed to status_url", "example": "t0psecr3t" }, "label_ids": { "type": "string", "description": "Array of IDs of labels to add to all messages sent (maximum 5). Does not apply when `message_type`=`service`, since the labels are determined by the service itself." }, "exclude_contact_id": { "type": "string", "description": "Optionally excludes one contact from receiving the message (only when group_id is set)" }, "replace_variables": { "type": "boolean", "description": "Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)", "default": "false", "example": true }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs.", "default": "false" }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link in the message. The following parameters are supported:\n\n `domain` (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.\n\n `expiration_sec` (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL.\n If null, the short links will not expire." }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n Use a https:// or http:// URL for media files that are already accessible via the internet.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project." }, "file_id": { "type": "string", "description": "ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required." }, "type": { "type": "string", "description": "MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media. Ignored if file_id is provided." } } }, "description": "Array of media attachments for the text message.\n\n If sending a type of message that doesn't support attachments (e.g. SMS), short links to each media URL will be appended to the end of the content (separated by a new line).\n\n Alternatively, you can use the `media_urls` parameter with an array of URL strings." }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables to set for each message" }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the messages in the broadcast. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "service_id": { "type": "string", "description": "Service to invoke for each recipient (when `message_type` is `call` or `service`)" }, "audio_url": { "type": "string", "description": "The URL of an MP3 file to play when the contact answers the call (when `message_type` is `call`).\n\n If `audio_url` is provided, the text-to-speech voice is not used to say `content`, although you can optionally use `content` to indicate the script for the audio.\n\n For best results, use an MP3 file containing only speech. Music is not recommended because the audio quality will be low when played over a phone line." }, "tts_lang": { "type": "string", "description": "The language of the text-to-speech voice (when `message_type` is `call`)", "enum": [ "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" ], "default": "en-US" }, "tts_voice": { "type": "string", "description": "The name of the text-to-speech voice (when message_type=call)", "enum": [ "female", "male" ], "default": "female" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Broadcast" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/send_multi": { "post": { "summary": "Send multiple messages", "operationId": "Project_sendMulti", "description": "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.", "tags": [ "Message" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "Content of the message to send" }, "to_number": { "type": "string", "description": "Phone number to send the message to" }, "status_url": { "type": "string", "description": "Webhook callback URL for this message" }, "status_secret": { "type": "string", "description": "POST parameter secret for status_url" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables for this message" }, "priority": { "type": "integer", "description": "Priority of this message (1 or 2)" } }, "required": [ "content", "to_number" ] }, "description": "Array of up to 100 objects with `content` and `to_number` properties. Each object may also contain the optional properties `status_url`, `status_secret`, `vars`, and/or `priority`, which override the parameters of the same name defined below, to allow passing different values for each message." }, "message_type": { "type": "string", "description": "Type of message to send. If `text`, will use the default text message type for the selected route.", "enum": { "0": "text", "1": "sms", "2": "mms", "4": "call", "5": "chat", "6": "service" }, "default": "text" }, "route_id": { "type": "string", "description": "ID of the phone or route to send the messages from", "default": "default sender route ID" }, "broadcast_id": { "type": "string", "description": "ID of an existing broadcast to associate the messages with" }, "broadcast_title": { "type": "string", "description": "Title of broadcast to create (when `broadcast_id` is not provided).\n When sending more than 100 messages over multiple API requests, you can associate all messages with the same broadcast by providing a `broadcast_title` parameter in the first\n API request, then retrieving the `broadcast_id` property from the API response, and passing it as the `broadcast_id` parameter in subsequent API requests.", "example": "API Broadcast" }, "status_url": { "type": "string", "description": "Webhook callback URL to be notified when message status changes", "example": "https://example.com/sms_status.php" }, "status_secret": { "type": "string", "description": "POST parameter 'secret' passed to status_url", "example": "t0psecr3t" }, "label_ids": { "type": "string", "description": "Array of IDs of labels to add to each message (maximum 5)" }, "replace_variables": { "type": "boolean", "description": "Set to true to evaluate variables like [[contact.name]] in message content. (See available variables)", "default": "false", "example": true }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs.", "default": "false" }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link in the message. The following parameters are supported:\n\n `domain` (string): A custom short domain name to use for the short links. The domain name must already be registered for your project or organization.\n\n `expiration_sec` (integer): The number of seconds after the message is created (queued to send) when the short links will stop forwarding to the destination URL.\n If null, the short links will not expire." }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n Use a https:// or http:// URL for media files that are already accessible via the internet.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project." }, "file_id": { "type": "string", "description": "ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required." }, "type": { "type": "string", "description": "MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media. Ignored if file_id is provided." } } }, "description": "Array of media attachments for the text message.\n\n If sending a type of message that doesn't support attachments (e.g. SMS), short links to each media URL will be appended to the end of the content (separated by a new line).\n\n Alternatively, you can use the `media_urls` parameter with an array of URL strings." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to apply to all messages. \n\n 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.\n\n For more details, see Route-Specific Parameters." }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables to store with the message" }, "priority": { "type": "integer", "description": "Priority of the message. Telerivet will attempt to send messages with higher priority numbers first (for example, so you can prioritize an auto-reply ahead of a bulk message to a large group).", "enum": [ 1, 2 ], "default": 1 }, "simulated": { "type": "boolean", "description": "Set to true to test the Telerivet API without actually sending a message from the route", "default": "false" } }, "required": [ "messages" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the created message" }, "status": { "type": "string", "description": "Status of the message" }, "error_message": { "type": "string", "description": "Error message if the message failed" } } }, "description": "List of objects representing each newly created message, with the same length and order as provided in the `messages` parameter in the API request.\n Each object has the `id` and `status` properties, and may have the property `error_message`.\n (Other properties of the Message object are omitted in order to reduce the amount of redundant data sent in each API response.)\n If the `messages` parameter in the API request contains items with `to_number` values that are associated with blocked contacts, the `id` and `status` properties corresponding to those items will be null, and no messages will be sent to those numbers." }, "broadcast_id": { "type": "string", "description": "ID of broadcast that these messages are associated with, if `broadcast_id` or `broadcast_title` parameter is provided in the API request." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/service_logs": { "get": { "summary": "Query service logs", "operationId": "Project_queryServiceLogs", "description": "Queries service log entries associated with this project.\n\n Note: Service logs are automatically deleted and no longer available via the API after approximately one month.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "service_id", "in": "query", "schema": { "type": "string", "description": "ID of Service" }, "description": "Filter logs generated by a particular service" }, { "name": "message_id", "in": "query", "schema": { "type": "string", "description": "ID of Message" }, "description": "Filter service logs related to a particular message" }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "description": "ID of Contact" }, "description": "Filter service logs related to a particular contact. Ignored if using the message_id parameter." }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter service logs by the time they were created" }, { "name": "execution_stats", "in": "query", "schema": { "type": "boolean" }, "description": "Show detailed execution stats for each log entry, if available.", "example": true }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/services": { "post": { "summary": "Create a service", "operationId": "Project_createService", "description": "Creates a new automated service.\n\n Only certain types of automated services can be created via the API. Other types of services can only be created via the web app.\n\n**Service Types:** See `x-service-types` in the API info section for a machine-readable list of all supported service types and their required configuration parameters.\n\n**Cloud Script Services:** When creating `*_script` service types, the `code` field contains JavaScript that runs in Telerivet's cloud script engine. See https://api.telerivet.com/script.d.ts for the full JavaScript API reference.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "description": "Service configuration. The `config` object structure depends on `service_type`. See `x-service-types` in the info section for all supported types and their config schemas.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateServiceRequest" }, "examples": { "webhook": { "summary": "Create incoming message webhook", "value": { "service_type": "incoming_message_webhook", "name": "My Webhook", "config": { "url": "https://example.com/webhook", "secret": "my_secret_123" } } }, "script": { "summary": "Create Cloud Script service", "description": "See https://api.telerivet.com/script.d.ts for the JavaScript API reference available in Cloud Script services.", "value": { "service_type": "incoming_message_script", "name": "Auto Reply Script", "config": { "code": "project.sendMessage({ to_number: contact.phone_number, content: 'Thanks for your message!' });" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Query services", "operationId": "Project_queryServices", "description": "Queries services within the given project.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter services by name" }, { "name": "active", "in": "query", "schema": { "type": "boolean" }, "description": "Filter services by active/inactive state", "example": true }, { "name": "context", "in": "query", "schema": { "type": "string", "enum": [ "message", "call", "ussd_session", "row", "contact", "project", "airtime_transaction" ] }, "description": "Filter services that can be invoked in a particular context", "example": "message" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "priority", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Service" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/services/{id}": { "get": { "summary": "Get service by ID", "operationId": "Project_getServiceById", "description": "Retrieves the service with the given ID.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the service" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update service details", "operationId": "Service_save", "description": "Updates writable fields on the given service.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the service", "example": "Poll Service" }, "active": { "type": "boolean", "description": "Whether the service is active or inactive. Inactive services are not automatically triggered and cannot be invoked via the API.", "example": true }, "priority": { "type": "integer", "description": "A number that determines the order that services are triggered when a particular event occurs (smaller numbers are triggered first). Any service can determine whether or not execution \"falls-through\" to subsequent services (with larger priority values) by setting the return_value variable within Telerivet's Rules Engine.", "example": 1 }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this service. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "response_table_id": { "type": "string", "description": "ID of the data table where responses to this service will be stored", "example": "DTf9fe14d9c306aed9" }, "phone_ids": { "type": "string", "description": "IDs of phones (basic routes) associated with this service, or null if the service is associated with all routes. Only applies for service types that handle incoming messages, voice calls, or USSD sessions." }, "message_types": { "type": "array", "items": { "type": "string" }, "description": "Types of messages that this service handles. Only provided for service types that handle incoming messages.", "enum": [ "text", "call", "ussd" ] }, "table_ids": { "type": "string", "description": "IDs of data tables that this service applies to, or null if this service applies to all data tables. Only provided for data row services (`data_row_script` and `data_row_actions`)." }, "message_statuses": { "type": "array", "items": { "type": "string" }, "description": "Message statuses that this service handles. Only provided for `message_status_actions` services.", "enum": [ "sent", "delivered", "failed", "failed_queued", "not_delivered" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags used to organize this service. Each tag can be up to 32 characters in length." }, "apply_mode": { "type": "string", "description": "If apply_mode is `unhandled`, the service will not be triggered if another service has already handled the incoming message. If apply_mode is `always`, the service will always be triggered regardless of other services. Only applies to services that handle incoming messages.", "enum": [ "always", "unhandled" ] }, "contact_number_filter": { "type": "string", "description": "If contact_number_filter is `long_number`, this service will only be triggered if the contact phone number has at least 7 digits (ignoring messages from shortcodes and alphanumeric senders). If contact_number_filter is `all`, the service will be triggered for all contact phone numbers. Only applies to services that handle incoming messages.", "enum": [ "long_number", "all" ] }, "show_action": { "type": "boolean", "description": "Whether this service is shown in the 'Actions' menu within the Telerivet web app when the service is active. Only provided for service types that are manually triggered." }, "direction": { "type": "string", "description": "Determines whether the service handles incoming voice calls, outgoing voice calls, or both. Only applies to services that handle voice calls.", "enum": [ "incoming", "outgoing", "both" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Service" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a service", "operationId": "Service_delete", "description": "Deletes this service.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/services/{id}/config": { "get": { "summary": "Get service configuration", "operationId": "Service_getConfig", "description": "Gets configuration specific to the type of automated service.\n\n Only certain types of services provide their configuration via the API. See Service Configuration Reference or the machine-readable [OpenAPI specification](https://api.telerivet.com/openapi.json) for available configuration options.\n\n**Response Schema:** The response object structure depends on the service's `service_type`:\n- `incoming_message_actions`: Returns `ServiceConfigIncomingMessageActions`\n- `contact_actions`: Returns `ServiceConfigContactActions`\n- `message_actions`: Returns `ServiceConfigMessageActions`\n- `project_actions`: Returns `ServiceConfigProjectActions`\n- `message_status_actions`: Returns `ServiceConfigMessageStatusActions`\n- `voice_actions`: Returns `ServiceConfigVoiceActions`\n- `ussd_actions`: Returns `ServiceConfigUssdActions`\n- `data_row_actions`: Returns `ServiceConfigDataRowActions`\n- `incoming_message_webhook`: Returns `ServiceConfigIncomingMessageWebhook`\n- `optin_optout`: Returns `ServiceConfigOptinOptout`\n- `keyword_auto_reply`: Returns `ServiceConfigKeywordAutoReply`\n- `messaging_poll`: Returns `ServiceConfigMessagingPoll`\n- `voice_poll`: Returns `ServiceConfigVoicePoll`\n- `scheduled_actions`: Returns `ServiceConfigScheduledActions`\n- `auto_reply`: Returns `ServiceConfigAutoReply`\n- `call_auto_reply`: Returns `ServiceConfigCallAutoReply`\n- `*_script` types: Returns `ServiceConfigScript` (code)\n- `opt_out_page`: Returns `ServiceConfigOptOutPage`\n- `button_page`: Returns `ServiceConfigButtonPage`\n- `custom_template_instance`: Returns `ServiceConfigCustomTemplateInstance`\n\nSee `x-service-types` in the API info section for complete schema details.\n\n**Cloud Script API Reference:** For comprehensive documentation of the JavaScript functions and objects available within Cloud Script services, see the TypeScript declarations at https://api.telerivet.com/script.d.ts.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" } ], "responses": { "200": { "description": "Service configuration object (structure depends on service_type)", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceConfigIncomingMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigContactActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigProjectActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageStatusActions" }, { "$ref": "#/components/schemas/ServiceConfigVoiceActions" }, { "$ref": "#/components/schemas/ServiceConfigUssdActions" }, { "$ref": "#/components/schemas/ServiceConfigDataRowActions" }, { "$ref": "#/components/schemas/ServiceConfigIncomingMessageWebhook" }, { "$ref": "#/components/schemas/ServiceConfigOptinOptout" }, { "$ref": "#/components/schemas/ServiceConfigKeywordAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigMessagingPoll" }, { "$ref": "#/components/schemas/ServiceConfigVoicePoll" }, { "$ref": "#/components/schemas/ServiceConfigScheduledActions" }, { "$ref": "#/components/schemas/ServiceConfigAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigCallAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigScript" }, { "$ref": "#/components/schemas/ServiceConfigOptOutPage" }, { "$ref": "#/components/schemas/ServiceConfigButtonPage" }, { "$ref": "#/components/schemas/ServiceConfigCustomTemplateInstance" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update service configuration", "operationId": "Service_setConfig", "description": "Updates configuration specific to the type of automated service.\n\n Only certain types of services support updating their configuration via the API.\n\n Note: when updating a service of type custom_template_instance,\n the validation script will be invoked when calling this method.\n\n**Request Schema:** The config object structure depends on the service's `service_type`. See `x-service-types` in the API info section for required fields per service type.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" } ], "responses": { "200": { "description": "Updated service configuration", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceConfigIncomingMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigContactActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigProjectActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageStatusActions" }, { "$ref": "#/components/schemas/ServiceConfigVoiceActions" }, { "$ref": "#/components/schemas/ServiceConfigUssdActions" }, { "$ref": "#/components/schemas/ServiceConfigDataRowActions" }, { "$ref": "#/components/schemas/ServiceConfigIncomingMessageWebhook" }, { "$ref": "#/components/schemas/ServiceConfigOptinOptout" }, { "$ref": "#/components/schemas/ServiceConfigKeywordAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigMessagingPoll" }, { "$ref": "#/components/schemas/ServiceConfigVoicePoll" }, { "$ref": "#/components/schemas/ServiceConfigScheduledActions" }, { "$ref": "#/components/schemas/ServiceConfigAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigCallAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigScript" }, { "$ref": "#/components/schemas/ServiceConfigOptOutPage" }, { "$ref": "#/components/schemas/ServiceConfigButtonPage" }, { "$ref": "#/components/schemas/ServiceConfigCustomTemplateInstance" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "requestBody": { "description": "Configuration object (structure depends on service_type)", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ServiceConfigIncomingMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigContactActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigProjectActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageStatusActions" }, { "$ref": "#/components/schemas/ServiceConfigVoiceActions" }, { "$ref": "#/components/schemas/ServiceConfigUssdActions" }, { "$ref": "#/components/schemas/ServiceConfigDataRowActions" }, { "$ref": "#/components/schemas/ServiceConfigIncomingMessageWebhook" }, { "$ref": "#/components/schemas/ServiceConfigOptinOptout" }, { "$ref": "#/components/schemas/ServiceConfigKeywordAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigMessagingPoll" }, { "$ref": "#/components/schemas/ServiceConfigVoicePoll" }, { "$ref": "#/components/schemas/ServiceConfigScheduledActions" }, { "$ref": "#/components/schemas/ServiceConfigAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigCallAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigScript" }, { "$ref": "#/components/schemas/ServiceConfigOptOutPage" }, { "$ref": "#/components/schemas/ServiceConfigButtonPage" }, { "$ref": "#/components/schemas/ServiceConfigCustomTemplateInstance" } ] }, "examples": { "webhook": { "summary": "Update webhook URL", "value": { "url": "https://example.com/new-webhook", "secret": "new_secret" } }, "script": { "summary": "Update script code", "value": { "code": "// Updated script\nproject.sendMessage({ to_number: contact.phone_number, content: 'Hello!' });" } } } } } } } }, "/v1/projects/{project_id}/services/{id}/invoke": { "post": { "summary": "Invoke a service", "operationId": "Service_invoke", "description": "Manually invoke this service in a particular context.\n\n For example, to send a poll to a particular contact (or resend the current question), you can invoke the poll service with context=contact, and `contact_id` as the ID of the contact to send the poll to. (To trigger a service to multiple contacts, use project.sendBroadcast. To schedule a service in the future, use project.scheduleMessage.)\n\n Or, to manually apply a service for an incoming message, you can invoke the service with `context`=`message`, `event`=`incoming_message`, and `message_id` as the ID of the incoming message. (This is normally not necessary, but could be used if you want to override Telerivet's standard priority-ordering of services.)", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "string", "description": "The name of the context in which this service is invoked", "enum": [ "message", "call", "ussd_session", "row", "contact", "project", "airtime_transaction" ], "example": "contact" }, "event": { "type": "string", "description": "The name of the event that is triggered (must be supported by this service)", "default": "default" }, "message_id": { "type": "string", "description": "The ID of the message this service is triggered for" }, "contact_id": { "type": "string", "description": "The ID of the contact this service is triggered for (either `contact_id` or `phone_number` is required if `context` is 'contact')", "example": "@{sigil}contact{dot}id" }, "phone_number": { "type": "string", "description": "The phone number of the contact this service is triggered for (either `contact_id` or `phone_number` is required if `context` is 'contact'). If no contact exists with this phone number, a new contact will be created." }, "row_id": { "type": "string", "description": "The ID of the data row this service is triggered for" }, "variables": { "type": "object", "additionalProperties": true, "description": "Object containing up to 25 temporary variable names and their corresponding values to set when invoking the service. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length. Arrays and objects are not supported. Within Custom Actions, each variable can be used like `[[$name]]` (with a leading `$` character and surrounded by double square brackets). Within a Cloud Script API service or JavaScript action, each variable will be available as a global JavaScript variable like `$name` (with a leading `$` character)." }, "route_id": { "type": "string", "description": "The ID of the phone or route that the service will use for sending messages by default" }, "async": { "type": "boolean", "description": "If set to true, the service will be invoked asynchronously. By default, queued services will be invoked one at a time for each project." } }, "required": [ "context" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "return_value": { "type": "string", "description": "Return value of the service. May be any JSON type (boolean, number, string, array, object, or null). (Undefined if async=true.)" }, "log_entries": { "type": "array", "items": { "type": "string" }, "description": "Array of log entry strings generated by the service. (Undefined if async=true.)" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "Array of error message strings generated by the service. (Undefined if async=true.)" }, "sent_messages": { "type": "array", "items": { "type": "string" }, "description": "Array of messages sent by the service." }, "airtime_transactions": { "type": "array", "items": { "type": "string" }, "description": "Array of airtime transactions sent by the service (Undefined if async=true.)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/services/{id}/states": { "get": { "summary": "Query contacts' states for a service", "operationId": "Service_queryContactStates", "description": "Query the current states of contacts for this service.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" }, { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "Filter states by id", "example": "q1" }, { "name": "vars", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Filter states by value of a custom variable (e.g. vars[email], vars[foo], etc.)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactServiceState" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/services/{id}/states/{contact_id}": { "get": { "summary": "Get a contact's state for a service", "operationId": "Service_getContactState", "description": "Gets the current state for a particular contact for this service.\n\n If the contact doesn't already have a state, this method will return a valid state object with id=null. However this object would not be returned by queryContactStates() unless it is saved with a non-null state id.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactServiceState" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update a contact's state for a service", "operationId": "Service_setContactState", "description": "Initializes or updates the current state for a particular contact for the given service. If the state id is null, the contact's state will be reset.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Arbitrary string representing the contact's current state for this service, e.g. 'q1', 'q2', etc.", "example": "q1" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this contact's state. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactServiceState" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Reset a contact's state for a service", "operationId": "Service_resetContactState", "description": "Resets the current state for a particular contact for the given service.", "tags": [ "Service" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Service" }, { "name": "contact_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Contact" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactServiceState" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables": { "get": { "summary": "Query data tables", "operationId": "Project_queryDataTables", "description": "Queries data tables within the given project.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter data tables by name" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataTable" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create or retrieve a data table by name", "operationId": "Project_getOrCreateDataTable", "description": "Gets or creates a data table by name.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the data table", "example": "Election Reports" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataTable" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}": { "get": { "summary": "Get data table by ID", "operationId": "Project_getDataTableById", "description": "Retrieves the data table with the given ID.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the data table" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataTable" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update table details", "operationId": "DataTable_save", "description": "Updates writable fields on the given data table.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the data table", "example": "Poll Responses" }, "show_add_row": { "type": "boolean", "description": "Whether to allow adding or importing rows via the web app", "example": false }, "show_stats": { "type": "boolean", "description": "Whether to show summary charts (pie charts, bar charts, tables of top values) for this data table in the web app", "example": true }, "show_contact_columns": { "type": "boolean", "description": "Whether to show 'Contact Name' and 'Phone Number' columns in the web app", "example": true }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this data table. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataTable" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a data table", "operationId": "DataTable_delete", "description": "Permanently deletes the given data table, including all its rows", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}/count_rows_by_value": { "get": { "summary": "Count rows by value", "operationId": "DataTable_countRowsByValue", "description": "Returns the number of rows for each value of a given variable. This can be used to get the total number of responses for each choice in a poll, without making a separate query for each response choice. The return value is an object mapping values to row counts, e.g. `{\"yes\":7,\"no\":3}`", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" }, { "name": "variable", "in": "query", "schema": { "type": "string" }, "description": "Variable of field to count by.", "required": true, "example": "q1_code" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}/fields": { "get": { "summary": "Get fields in data table", "operationId": "DataTable_getFields", "description": "Gets a list of all fields (columns) defined for this data table. The return value is an array of objects with the properties 'name', 'variable', 'type', 'order', 'readonly', and 'lookup_key'. (Fields are automatically created any time a DataRow's 'vars' property is updated.)", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the field" }, "variable": { "type": "string", "description": "Variable name used in the API" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "readonly": { "type": "boolean", "description": "Whether the field is read-only" }, "lookup_key": { "type": "boolean", "description": "Whether the field is a lookup key" }, "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Option value stored in the database" }, "label": { "type": "string", "description": "Option label displayed to users" } } }, "description": "For select or radio fields, the list of options" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update fields in data table", "operationId": "DataTable_updateFields", "description": "Updates metadata for one or more fields (columns) in the data table. Only the specified fields are updated; other fields are not affected.\n\n To delete a field, include an object with the `variable` and `delete` properties set (e.g. `{\"variable\": \"my_field\", \"delete\": true}`). Deleting a field will also clear the corresponding variable on all rows in the table.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "type": "array", "items": { "type": "object", "properties": { "variable": { "type": "string", "description": "Variable name of the field" }, "name": { "type": "string", "description": "Display name for the field" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "readonly": { "type": "boolean", "description": "Whether the field is read-only" }, "lookup_key": { "type": "boolean", "description": "Whether the field is a lookup key" }, "items": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Option value stored in the database" }, "label": { "type": "string", "description": "Option label displayed to users" } } }, "description": "For select or radio fields, the list of options" }, "delete": { "type": "boolean", "description": "Set to true to delete this field. Other properties besides `variable` are ignored when deleting." } }, "required": [ "variable" ] }, "description": "Array of up to 100 objects describing the fields to create, update, or delete. Each object must contain a `variable` property. Only the properties provided for each field will be updated." } }, "required": [ "metadata" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the field" }, "variable": { "type": "string", "description": "Variable name used in the API" }, "type": { "type": "string", "description": "Field type" }, "order": { "type": "integer", "description": "Display order of the field" }, "readonly": { "type": "boolean", "description": "Whether the field is read-only" }, "lookup_key": { "type": "boolean", "description": "Whether the field is a lookup key" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}/import_rows": { "post": { "summary": "Import data rows", "operationId": "DataTable_importRows", "description": "Creates and/or updates up to 200 rows in a single API call. When creating or updating a large number of rows, this method is significantly faster than sending a separate API request for each row.\n\n By default, a new row will be created for each item. To update existing rows, set the `lookup_key` parameter to match rows by ID, contact, or the value of a custom variable.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables and values for this data row. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "contact_id": { "type": "string", "description": "ID of the contact associated with this row" }, "from_number": { "type": "string", "description": "Phone number associated with this row" }, "id": { "type": "string", "description": "ID of an existing row (only used if `lookup_key` is 'id')" } } }, "description": "Array of up to 200 objects which may contain the properties `vars` (object), `contact_id` (string), `from_number` (string), and `id` (string). All properties are optional, unless used as a lookup key." }, "lookup_key": { "type": "string", "description": "The field used to search for a matching row, or 'none' to always create a new row. To search by a custom variable, precede the variable name with 'vars.'.", "enum": [ "none", "id", "contact_id", "vars.variable_name" ], "default": "none" } }, "required": [ "rows" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the row" }, "time_created": { "type": "integer", "description": "Time the row was created (UNIX timestamp)" }, "time_updated": { "type": "integer", "description": "Time the row was last updated (UNIX timestamp)" }, "contact_id": { "type": "string", "description": "ID of the associated contact (if any)" }, "from_number": { "type": "string", "description": "Phone number associated with this row (if any)" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this row" } }, "required": [ "id" ] }, "description": "List of objects representing each row, in the same order as provided in the `rows` parameter in the API request." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}/rows": { "get": { "summary": "Query rows in a data table", "operationId": "DataTable_queryRows", "description": "Queries rows in this data table.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" }, { "name": "time_created", "in": "query", "schema": { "type": "integer", "format": "unix-timestamp", "description": "Unix timestamp in seconds" }, "description": "Filter data rows by the time they were created" }, { "name": "contact_id", "in": "query", "schema": { "type": "string", "description": "ID of Contact" }, "description": "Filter data rows associated with a particular contact" }, { "name": "vars", "in": "query", "schema": { "type": "object", "additionalProperties": true }, "description": "Filter data rows by value of a custom variable (e.g. vars[q1], vars[foo], etc.)" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataRow" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Add new data row", "operationId": "DataTable_createRow", "description": "Adds a new row to this data table.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "ID of the contact that this row is associated with (if applicable)" }, "from_number": { "type": "string", "description": "Phone number that this row is associated with (if applicable)", "example": "+16505550123" }, "vars": { "type": "string", "description": "Custom variables and values to set for this data row. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}/rows/{row_id}": { "get": { "summary": "Get data row by ID", "operationId": "DataTable_getRowById", "description": "Retrieves the row in the given table with the given ID.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" }, { "name": "row_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the row" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{table_id}/rows/{id}": { "post": { "summary": "Update data row", "operationId": "DataRow_save", "description": "Updates writable fields on the given data data row.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Table" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataRow" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "ID of the contact this row is associated with (or null if not associated with any contact)", "example": "CTa1299c3d0e371023" }, "from_number": { "type": "string", "description": "Phone number that this row is associated with (or null if not associated with any phone number)", "example": "+16505550123" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this data row. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataRow" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete data row", "operationId": "DataRow_delete", "description": "Deletes this data row.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Table" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataRow" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}/views": { "get": { "summary": "Query views of a data table", "operationId": "DataTable_queryViews", "description": "Queries views of this data table.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "Filter views by name" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default", "name" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataView" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a data table view", "operationId": "DataTable_createView", "description": "Creates a new view of this data table, defined by a filter on its rows. The view's filter conditions cannot be changed after the view is created (although the view can be renamed or deleted).\n\n Telerivet will automatically store the count of rows matching each data view once a day, making it possible to retrieve historical statistics for the number of rows matching the filter, but only for dates after the view is created.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the view (must be unique within the data table)", "example": "Completed Responses" }, "filters": { "type": "object", "additionalProperties": true, "description": "Key-value pairs of conditions that rows must match to be included in the view. To filter by a custom variable, precede the variable name with 'vars.' (conditions on custom variables may also be provided as a nested object under a `vars` key, e.g. `{\"vars\": {\"q1\": \"yes\"}}`); other supported keys are `id`, `time_created`, `time_updated`, `contact_id`, `contact_name`, and `from_number`. Each value is either a value to match exactly, or an object with an operator such as `ne`, `prefix`, `gte`, `gt`, `lte`, `lt`, `exists`, or `not_exists` as the key (e.g. `{\"gte\": 10}`)." } }, "required": [ "name", "filters" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{id}/views/{view_id}": { "get": { "summary": "Get data table view by ID", "operationId": "DataTable_getViewById", "description": "Retrieves the view of the given table with the given ID.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataTable" }, { "name": "view_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the view" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{table_id}/views/{id}": { "post": { "summary": "Update view details", "operationId": "DataView_save", "description": "Updates writable fields on the given data table view.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Table" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataView" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the data view", "example": "Completed Responses" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataView" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a data table view", "operationId": "DataView_delete", "description": "Permanently deletes the given view of a data table (does not delete any rows in the table)", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Table" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataView" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tables/{table_id}/views/{id}/rows": { "get": { "summary": "Query rows in a data table view", "operationId": "DataView_queryRows", "description": "Queries rows matching this view's filter conditions.", "tags": [ "DataTable" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "table_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Table" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the DataView" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DataRow" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tasks": { "post": { "summary": "Create a task", "operationId": "Project_createTask", "description": "Creates and starts an asynchronous task that is applied to all entities matching a filter (e.g. contacts, messages, or data rows).\n Tasks are designed to efficiently process a large number of entities. When processing a large number of entities,\n tasks are much faster than using the API to query and loop over all objects matching a filter.\n\n Several different types of tasks are supported, including applying services to contacts, messages, or data rows;\n adding or removing contacts from a group; blocking or unblocking sending messages to a contact; updating a custom variable;\n deleting contacts, messages, or data rows; or exporting data to CSV.\n\n 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`),\n 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\n to store aggregate statistics for the rows matching the filter.", "tags": [ "Task" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "task_type": { "type": "string", "description": "Type of task to create. Each `task_type` applies to a certain type of entity (such as a contact, message, or data row).\n\n Tasks for contacts:\n\n - update_contact_var\n - add_group_members\n - remove_group_members\n - set_conversation_status\n - set_send_blocked\n - apply_service_to_contacts\n - delete_contacts\n - export_contacts\n\n Tasks for data rows:\n\n - update_row_var\n - apply_service_to_rows\n - delete_rows\n - export_rows\n\n Tasks for messages:\n\n - cancel_messages\n - resend_messages\n - retry_message_services\n - apply_service_to_messages\n - add_label\n - remove_label\n - update_message_var\n - delete_messages\n - export_messages", "example": "add_group_members" }, "task_params": { "type": "object", "additionalProperties": true, "description": "Parameters applied to all matching rows (specific to `task_type`).\n\n **apply_service_to_contacts**, **apply_service_to_messages**, **apply_service_to_rows**:\n \n - service_id - The ID of the service to apply (string) \n\n - variables - Optional object containing up to 25 temporary variable names and their corresponding values to set when invoking the service. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length. Arrays and objects are not supported. Within Custom Actions, each variable can be used like [[$name]] (with a leading $ character and surrounded by double square brackets). Within a Cloud Script API service or JavaScript action, each variable will be available as a global JavaScript variable like $name (with a leading $ character). (object) \n\n \n
\n **update_contact_var**, **update_message_var**, **update_row_var**:\n \n - variable - The custom variable name (string) \n\n - value - The value to set (string, boolean, float, null) \n\n \n
\n **add_group_members**, **remove_group_members**:\n \n - group_id - The ID of the group (string) \n\n \n
\n **add_label**, **remove_label**:\n \n - label_id - The ID of the label (string) \n\n \n
\n **resend_messages**:\n \n - route_id - ID of the new route to use, or null to use the original route (string) \n\n \n
\n **set_send_blocked**:\n \n - send_blocked - true to block sending messages, false to unblock sending messages (boolean) \n\n \n
\n **set_conversation_status**:\n \n - conversation_status - \"active\", \"handled\", or \"closed\" (string) \n\n \n
\n **export_contacts**, **export_messages**, **export_rows**:\n \n - storage_id - ID of a storage provider where the CSV file will be saved. (string)\n\n Currently only AWS S3 is supported as a storage provider.\n This requires creating a S3 bucket in your own AWS account, as well as an IAM user with access key and secret that has permission to write to that bucket.\n You can configure your own S3 bucket as a storage provider on the [Storage Providers](https://telerivet.com/dashboard/a/storage) page.\n\n Direct downloads are not supported when exporting data via the API.\n (string) \n\n - filename - Path within the storage backend where the CSV file will be saved \n\n - column_ids - IDs of columns to save in the CSV file. If not provided, all default columns will be saved. (array of strings, optional) \n\n \n
\n **delete_contacts**, **delete_messages**, **delete_rows**, **cancel_messages**, **retry_message_services**:
\n No parameters." }, "filter_type": { "type": "string", "description": "Type of filter defining the rows that the task is applied to.\n\n Each `filter_type` queries a certain type of entity (such as contacts, messages, or data rows).\n\n In general, the `task_type` and the `filter_type` must return the same type of entity; however, tasks applied to contacts (other than `export_contacts`) can also be applied\n when the filter returns entities that are associated with a contact, such as messages or data rows. (Note that in this case, it is possible for the task to be applied multiple times to an individual contact if multiple messages or data rows are associated with the same contact.)", "enum": [ "query_contacts", "contact_ids", "query_rows", "row_ids", "query_messages", "message_ids" ], "example": "query_contacts" }, "filter_params": { "type": "object", "additionalProperties": true, "description": "Parameters defining the rows that the task is applied to (specific to `filter_type`).\n\n **`query_contacts`**:
\n The same filter parameters as used by project.queryContacts. If you want to apply the task to all contacts, use the parameters {\"all\": true}.\n\n **`contact_ids`**:\n \n - `contact_ids` - IDs of up to 100 contacts to apply this task to (array of strings) \n\n \n\n **`query_messages`**:
\n The same filter parameters as used by project.queryMessages. If you want to apply the task to all messages, use the parameters {\"all\": true}.\n\n **`message_ids`**:\n \n - `message_ids` - IDs of up to 100 messages to apply this task to (array of strings) \n\n \n\n **`query_rows`**:
\n The same filter parameters as used by table.queryRows. If you want to apply the task to all rows in the table, use the parameters {\"all\": true}.\n\n **`row_ids`**:\n \n - `row_ids` - IDs of up to 100 data rows to apply this task to (array of strings) \n\n " }, "table_id": { "type": "string", "description": "ID of the data table this task is applied to (if applicable).\n\n Required if filter_type is `query_rows` or `row_ids`." }, "vars": { "type": "object", "additionalProperties": true, "description": "Initial custom variables to set for the task.\n\n If the task applies a service, the service can read and write custom variables on the task object (e.g. `task.vars.example`), such as\n to store aggregate statistics for the rows matching the filter." } }, "required": [ "task_type", "filter_type", "filter_params" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "get": { "summary": "Query tasks", "operationId": "Project_queryTasks", "description": "Queries batch tasks within the given project.", "tags": [ "Task" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Task" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tasks/{id}": { "get": { "summary": "Get task by ID", "operationId": "Project_getTaskById", "description": "Retrieves the task with the given ID.", "tags": [ "Task" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the task" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/tasks/{id}/cancel": { "post": { "summary": "Cancel a task", "operationId": "Task_cancel", "description": "Cancels a task that is not yet complete.", "tags": [ "Task" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Task" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/users": { "get": { "summary": "Get user accounts", "operationId": "Project_getUsers", "description": "Returns an array of user accounts that have access to this project. Each item in the array is an object containing `id`, `email`, and `name` properties. (The id corresponds to the `user_id` property of the Message object.)", "tags": [ "Project" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the user" }, "email": { "type": "string", "description": "Email address of the user" }, "name": { "type": "string", "description": "Name of the user" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/webhooks": { "get": { "summary": "Query webhooks", "operationId": "Project_queryWebhooks", "description": "Queries webhooks within the given project.", "tags": [ "Webhook" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "sort", "in": "query", "schema": { "type": "string", "enum": [ "default" ], "default": "default" }, "description": "Sort the results based on a field" }, { "name": "sort_dir", "in": "query", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" }, "description": "Sort the results in ascending or descending order" }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "default": 50 }, "description": "Number of results returned per page (max 500)" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "Number of items to skip from beginning of result set" }, { "name": "marker", "in": "query", "schema": { "type": "string" }, "description": "'next_marker' property returned by a previous call to this API method, indicating where the next page of results should start." }, { "name": "count", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "If true, the API will return the count of items matching the filter, instead of the items themselves" } ], "responses": { "200": { "description": "Successful response. When count=1 parameter is provided, returns {\"count\": N} instead.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" }, "description": "Array of results (omitted when count=1)" }, "truncated": { "type": "boolean", "description": "True if there are more results" }, "next_marker": { "type": "string", "description": "Marker for pagination" }, "page_size": { "type": "integer", "description": "Number of results per page" }, "sort_dir": { "type": "string", "enum": [ "asc", "desc" ], "description": "Sort direction" }, "count": { "type": "integer", "description": "Total count of matching items (only when count=1 parameter is provided)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Create a new webhook", "operationId": "Project_createWebhook", "description": "Creates a new webhook that will be triggered when specific events occur within the project.\n\n Note: The Webhook object is not used for notifying your server when incoming messages are received. To notify a URL when incoming messages are received, you can configure a webhook by creating a Service with type incoming_message_webhook.", "tags": [ "Webhook" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL to send webhook requests to. Must start with https:// or http://.", "example": "https://example.com/webhook" }, "secret": { "type": "string", "description": "Secret to include when sending webhook requests (up to 200 characters). Telerivet will send the secret in the password field of HTTP basic auth (with username 'telerivet').", "example": "my-webhook-secret" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Array of event types to trigger this webhook. Valid event types are: `send_status` (message status updates), `send_broadcast` (broadcast sent), `contact_update` (contact added/updated/deleted), `message_metadata` (message metadata updated)." } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/projects/{project_id}/webhooks/{id}": { "get": { "summary": "Get webhook by ID", "operationId": "Project_getWebhookById", "description": "Retrieves the webhook with the given ID.", "tags": [ "Webhook" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the webhook" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "summary": "Update webhook", "operationId": "Webhook_save", "description": "Updates the webhook configuration.", "tags": [ "Webhook" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Webhook" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "URL that webhook requests are sent to", "example": "https://example.com/webhook" }, "secret": { "type": "string", "description": "Secret included with webhook requests for authentication (sent as HTTP basic auth password with username 'telerivet')", "example": "my-webhook-secret" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Array of event types that trigger this webhook. Possible values: `send_status` (message status updates), `send_broadcast` (broadcast sent), `contact_update` (contact added/updated/deleted), `message_metadata` (message metadata updated)" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "summary": "Delete a webhook", "operationId": "Webhook_delete", "description": "Deletes the webhook.", "tags": [ "Webhook" ], "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Project" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the Webhook" } ], "responses": { "200": { "description": "Successful response" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic", "description": "API key as username, password ignored" }, "oauth2": { "type": "oauth2", "description": "OAuth 2.0 authorization. Tokens can be scoped to specific permissions and optionally restricted to a single organization.", "flows": { "authorizationCode": { "authorizationUrl": "https://telerivet.com/oauth/authorize", "tokenUrl": "https://api.telerivet.com/oauth/token", "refreshUrl": "https://api.telerivet.com/oauth/token", "scopes": { "messages:read": "View messages", "messages:send": "Send messages", "messages:delete": "Delete messages", "contacts:read": "View contacts", "contacts:write": "Edit contacts", "services:read": "View automated services", "services:write": "Edit automated services", "data:read": "View data tables", "data:write": "Edit data tables", "routes:read": "View routes", "routes:write": "Edit routes", "airtime:read": "View airtime", "stats:read": "View statistics", "users:read": "View user permissions", "billing:read": "View billing information", "projects:write": "Edit project settings", "account:write": "Edit organization settings", "offline_access": "Maintain access when you are not using the application" } }, "deviceAuthorization": { "deviceAuthorizationUrl": "https://api.telerivet.com/oauth/device_authorization", "tokenUrl": "https://api.telerivet.com/oauth/token", "scopes": { "messages:read": "View messages", "messages:send": "Send messages", "messages:delete": "Delete messages", "contacts:read": "View contacts", "contacts:write": "Edit contacts", "services:read": "View automated services", "services:write": "Edit automated services", "data:read": "View data tables", "data:write": "Edit data tables", "routes:read": "View routes", "routes:write": "Edit routes", "airtime:read": "View airtime", "stats:read": "View statistics", "users:read": "View user permissions", "billing:read": "View billing information", "projects:write": "Edit project settings", "account:write": "Edit organization settings", "offline_access": "Maintain access when you are not using the application" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "string", "description": "Machine-readable error code" }, "param": { "type": "string", "description": "Parameter that caused the error (if applicable)" } } } } }, "WebhookIncomingMessage": { "type": "object", "description": "Payload sent when an incoming message is received. Telerivet POSTs this to your webhook URL.", "properties": { "event": { "type": "string", "description": "Event type identifier", "enum": [ "incoming_message" ] }, "id": { "type": "string", "description": "Unique message ID (max 34 characters)", "maxLength": 34 }, "message_type": { "type": "string", "description": "Type of message received", "enum": [ "sms", "mms", "ussd", "call" ] }, "content": { "type": "string", "description": "Text content of the message" }, "from_number": { "type": "string", "description": "Phone number or sender ID that sent the message (raw format from network)" }, "from_number_e164": { "type": "string", "description": "Sender phone number normalized to E.164 format (e.g., +16505550123)" }, "to_number": { "type": "string", "description": "Your phone number that received the message" }, "time_created": { "type": "integer", "description": "Unix timestamp when Telerivet received the message" }, "time_sent": { "type": "integer", "description": "Unix timestamp when message was sent (from network, may not always be available)" }, "contact_id": { "type": "string", "description": "ID of the contact who sent the message", "maxLength": 34 }, "phone_id": { "type": "string", "description": "ID of the phone/route that received the message", "maxLength": 34 }, "service_id": { "type": "string", "description": "ID of the webhook service triggering this request", "maxLength": 34 }, "message_service_id": { "type": "string", "description": "ID of the service that handled this message", "maxLength": 34 }, "project_id": { "type": "string", "description": "ID of the Telerivet project", "maxLength": 34 }, "secret": { "type": "string", "description": "Secret string for verifying the request came from Telerivet" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string" }, "filename": { "type": "string" }, "size": { "type": "integer" } } }, "description": "Media attachments (for MMS)" }, "contact": { "type": "object", "additionalProperties": true, "description": "Contact information (name, vars, etc.)" }, "state": { "type": "object", "properties": { "id": { "type": "string", "description": "Current state ID in conversation flow" }, "vars": { "type": "object", "additionalProperties": true } }, "description": "Contact service state for multi-step conversations" }, "phone": { "type": "object", "additionalProperties": true, "description": "Phone/route information" } }, "required": [ "event", "id", "message_type", "from_number", "to_number", "project_id" ] }, "WebhookSendStatus": { "type": "object", "description": "Payload sent when outgoing message status changes (sent, delivered, failed, etc.)", "properties": { "event": { "type": "string", "description": "Event type identifier", "enum": [ "send_status" ] }, "id": { "type": "string", "description": "Unique message ID", "maxLength": 34 }, "status": { "type": "string", "description": "Current message status", "enum": [ "queued", "sent", "failed", "failed_queued", "delivered", "not_delivered", "cancelled" ] }, "error_message": { "type": "string", "description": "Error description if message failed" }, "message_type": { "type": "string", "description": "Either sms, mms, ussd, or call. Other message types may be added in the future.", "enum": [ "sms", "mms", "ussd", "call" ] }, "content": { "type": "string", "description": "Message content" }, "from_number": { "type": "string", "description": "Sender phone number" }, "to_number": { "type": "string", "description": "Recipient phone number" }, "time_created": { "type": "integer", "description": "Unix timestamp when message was queued" }, "time_sent": { "type": "integer", "description": "Unix timestamp when message was sent" }, "time_clicked": { "type": "integer", "description": "Unix timestamp when short link was first clicked" }, "contact_id": { "type": "string", "description": "The ID of the contact that the message was sent to", "maxLength": 34 }, "phone_id": { "type": "string", "description": "The ID of the phone that the message was sent from", "maxLength": 34 }, "project_id": { "type": "string", "description": "The ID of the Telerivet project associated with this message", "maxLength": 34 }, "secret": { "type": "string", "description": "An optional secret string that you previously specified, so that you can verify that the request came from Telerivet." }, "contact": { "type": "object", "additionalProperties": true, "description": "Information about the contact who sent or received the message, as stored in your Telerivet contacts database.\n The POST parameters are named so that some languages (including PHP) will automatically parse the parameters into an object.\n The Webhook API sends the same contact properties as are available in the REST API. See all" } }, "required": [ "event", "id", "status", "project_id" ] }, "WebhookBroadcast": { "type": "object", "description": "Payload sent when a broadcast is created", "properties": { "event": { "type": "string", "description": "Event type identifier", "enum": [ "send_broadcast" ] }, "id": { "type": "string", "description": "Unique broadcast ID", "maxLength": 34 }, "content": { "type": "string", "description": "Message content being broadcast" }, "recipients_str": { "type": "string", "description": "Human-readable description of recipients" }, "recipients": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "Recipient details" }, "estimated_count": { "type": "integer", "description": "Estimated number of messages to be sent" }, "route_id": { "type": "string", "description": "The ID of the route or phone that the broadcast is sent from.", "maxLength": 34 }, "project_id": { "type": "string", "description": "The ID of the Telerivet project associated with this broadcast", "maxLength": 34 }, "user_name": { "type": "string", "description": "Name of user who sent the broadcast" }, "user_email": { "type": "string", "description": "Email of user who sent the broadcast" }, "secret": { "type": "string", "description": "An optional secret string that you previously specified, so that you can verify that the request came from Telerivet." } }, "required": [ "event", "id", "project_id" ] }, "WebhookContactUpdate": { "type": "object", "description": "Payload sent when a contact is added, updated, or deleted", "properties": { "event": { "type": "string", "description": "Event type identifier", "enum": [ "contact_update" ] }, "update_type": { "type": "string", "description": "Type of contact update", "enum": [ "add", "auto_add", "update", "update_field", "add_group", "remove_group", "block_send", "unblock_send", "delete" ] }, "id": { "type": "string", "description": "Contact ID", "maxLength": 34 }, "phone_number": { "type": "string", "description": "Phone number of the contact" }, "name": { "type": "string", "description": "Name of the contact" }, "send_blocked": { "type": "boolean", "description": "True if sending to this contact is blocked" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom contact variables" }, "group_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of groups this contact belongs to" }, "project_id": { "type": "string", "description": "The ID of the Telerivet project", "maxLength": 34 }, "secret": { "type": "string", "description": "An optional secret string that you specified in your Project Settings, so that you can verify that the request came from Telerivet." } }, "required": [ "event", "update_type", "id", "project_id" ] }, "WebhookMessageMetadata": { "type": "object", "description": "Payload sent when message metadata is updated (labels, stars, IVR variables)", "properties": { "event": { "type": "string", "description": "Event type identifier", "enum": [ "message_metadata" ] }, "update_type": { "type": "string", "description": "Type of metadata update", "enum": [ "star", "unstar", "add_label", "remove_label", "set_variable", "call_complete" ] }, "id": { "type": "string", "description": "Message ID", "maxLength": 34 }, "starred": { "type": "boolean", "description": "Whether message is starred" }, "label_ids": { "type": "array", "items": { "type": "string" }, "description": "IDs of labels applied to message" }, "vars": { "type": "object", "additionalProperties": true, "description": "Message variables (IVR key presses, recording URLs)" }, "in_progress": { "type": "boolean", "description": "True if call is currently in progress (voice calls only)" }, "project_id": { "type": "string", "description": "The ID of the Telerivet project", "maxLength": 34 }, "secret": { "type": "string", "description": "An optional secret string that you specified in your Project Settings, so that you can verify that the request came from Telerivet." }, "contact": { "type": "object", "additionalProperties": true, "description": "Information about the contact who sent or received the message, as stored in your Telerivet contacts database.\n The POST parameters are named so that some languages (including PHP) will automatically parse the parameters into an object.\n The Webhook API sends the same contact properties as are available in the REST API. See all" } }, "required": [ "event", "update_type", "id", "project_id" ] }, "WebhookResponse": { "type": "object", "description": "Optional JSON response your webhook can return to send autoreplies or update variables", "properties": { "messages": { "type": "array", "description": "Array of messages to send as autoreplies", "items": { "type": "object", "properties": { "content": { "type": "string", "description": "Message text to send" }, "to_number": { "type": "string", "description": "Recipient phone number (defaults to sender of incoming message)" }, "message_type": { "type": "string", "description": "Type of message to send", "enum": [ "sms", "ussd" ], "default": "sms" }, "route_id": { "type": "string", "description": "Phone/route ID to send from (defaults to receiving phone)" }, "status_url": { "type": "string", "description": "Webhook URL for delivery status updates" }, "status_secret": { "type": "string", "description": "Secret for status webhook verification" } }, "required": [ "content" ] } }, "variables": { "type": "object", "additionalProperties": true, "description": "Variables to update in Rules Engine (e.g., contact.name, state.id, $foo)", "example": { "contact.name": "John Smith", "state.id": "next_step", "$foo": 42 } } } }, "ServiceConfigIncomingMessageWebhook": { "type": "object", "properties": { "url": { "type": "string", "description": "Webhook URL that will receive POST requests when messages arrive. HTTPS is recommended for production use." }, "secret": { "type": "string", "description": "Secret string passed as POST parameter for request verification. Auto-generated if not provided." } }, "required": [ "url" ], "description": "Configuration for incoming_message_webhook service type" }, "ServiceConfigOptinOptout": { "type": "object", "properties": { "subscribe_keywords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } } }, "description": "Keywords that subscribe a contact (up to 20 keywords, each 1-30 characters). Matching is case-insensitive." }, "subscribe_reply": { "$ref": "#/components/schemas/MessageBody", "description": "Reply sent when a contact subscribes. Leave blank to not send a reply." }, "unsubscribe_keywords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } } }, "description": "Keywords that unsubscribe a contact (up to 20 keywords, each 1-30 characters). Matching is case-insensitive." }, "unsubscribe_reply": { "$ref": "#/components/schemas/MessageBody", "description": "Reply sent when a contact unsubscribes. Leave blank to not send a reply." }, "subscriber_group": { "type": "string", "description": "Name of the contact group containing subscribers. The group is created if it does not already exist." }, "unsubscriber_group": { "type": "string", "description": "Name of the contact group containing unsubscribers. Required when add_unsubscriber or remove_unsubscriber action is enabled. The group is created if it does not already exist (with sending blocked)." }, "subscribe_label": { "type": "string", "description": "Name of the message label applied on subscribe. Required when add_subscribe_label action is enabled." }, "unsubscribe_label": { "type": "string", "description": "Name of the message label applied on unsubscribe. Required when add_unsubscribe_label action is enabled." }, "actions": { "type": "object", "properties": { "add_subscriber": { "type": "boolean", "description": "Add the contact to the subscriber group on subscribe.", "default": true }, "remove_subscriber": { "type": "boolean", "description": "Remove the contact from the subscriber group on unsubscribe.", "default": true }, "add_unsubscriber": { "type": "boolean", "description": "Add the contact to the unsubscriber group on unsubscribe.", "default": true }, "remove_unsubscriber": { "type": "boolean", "description": "Remove the contact from the unsubscriber group on subscribe.", "default": true }, "add_subscribe_label": { "type": "boolean", "description": "Apply the subscribe label to the message on subscribe.", "default": true }, "add_unsubscribe_label": { "type": "boolean", "description": "Apply the unsubscribe label to the message on unsubscribe.", "default": true }, "subscribe_unblock": { "type": "boolean", "description": "Unblock the contact on subscribe.", "default": true }, "unsubscribe_block": { "type": "boolean", "description": "Block the contact on unsubscribe.", "default": true } }, "description": "Actions to perform on subscribe and unsubscribe. Each action defaults to true; set to false to disable. At least one subscribe action must be enabled when subscribe_keywords is set, and at least one unsubscribe action when unsubscribe_keywords is set." } }, "required": [ "subscriber_group" ], "description": "Configuration for optin_optout service type" }, "ServiceConfigKeywordAutoReply": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "keywords": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" } } }, "description": "Up to 20 keywords (each up to 70 characters). Matching is case-insensitive." }, "reply": { "$ref": "#/components/schemas/MessageBody", "description": "Reply message body." } }, "required": [ "keywords", "reply" ] }, "description": "Up to 100 items. Each item defines a list of keywords and the reply sent when an incoming message matches any of the keywords. Items are evaluated in order and only the first matching item is applied." } }, "required": [ "items" ], "description": "Configuration for keyword_auto_reply service type" }, "ServiceConfigMessagingPoll": { "type": "object", "properties": { "response_mode": { "type": "string", "description": "Controls how responses are collected.", "enum": [ "outgoing", "direct", "keyword" ], "default": "outgoing" }, "trigger_keyword": { "type": "string", "description": "Keyword that starts the poll when response_mode is \"keyword\"." }, "multiple_action": { "type": "string", "description": "Action when a contact tries to respond multiple times.", "enum": [ "allow", "ignore" ], "default": "allow" }, "end_reply": { "$ref": "#/components/schemas/MessageBody", "description": "Message sent when the poll is completed." }, "label_id": { "type": "string", "description": "ID of the label to apply to poll messages." }, "sample_group_id": { "type": "string", "description": "ID of the contact group for poll recipients." }, "respondent_group_id": { "type": "string", "description": "ID of the contact group for contacts who have completed the poll." }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/PollQuestion" }, "description": "Array of poll questions." } }, "required": [ "questions" ], "description": "Configuration for messaging_poll service type" }, "ServiceConfigVoicePoll": { "type": "object", "properties": { "incoming_call_mode": { "type": "string", "description": "Controls how incoming calls trigger the poll. \"any\" runs the poll for any incoming call. \"recipients\" runs the poll only for contacts in the sample group. \"none\" disables incoming calls (only outgoing). Setting any value other than \"none\" also sets the service direction to handle incoming calls.", "enum": [ "any", "recipients", "none" ], "default": "none" }, "multiple_action": { "type": "string", "description": "Action when a contact tries to respond multiple times.", "enum": [ "allow", "ignore" ], "default": "allow" }, "start_audio": { "$ref": "#/components/schemas/VoiceAudio", "description": "Audio played when the call starts, before the first question." }, "end_audio": { "$ref": "#/components/schemas/VoiceAudio", "description": "Audio played when the poll is completed." }, "label_id": { "type": "string", "description": "ID of the label to apply to poll messages." }, "sample_group_id": { "type": "string", "description": "ID of the contact group for poll recipients." }, "respondent_group_id": { "type": "string", "description": "ID of the contact group for contacts who have completed the poll." }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/VoicePollQuestion" }, "description": "Array of poll questions. Voice polls support question types \"keypress\", \"recording\", \"digits\", and \"open\". For voice polls, the question `body` is an audio object (with `mode`, `text` or `audio_url`, etc.) rather than a text message body." } }, "required": [ "questions" ], "description": "Configuration for voice_poll service type" }, "ServiceConfigAutoReply": { "type": "object", "properties": { "reply": { "$ref": "#/components/schemas/MessageBody", "description": "Reply message body." } }, "required": [ "reply" ], "description": "Configuration for auto_reply service type" }, "ServiceConfigCallAutoReply": { "type": "object", "properties": { "reply": { "$ref": "#/components/schemas/MessageBody", "description": "Reply message body." } }, "required": [ "reply" ], "description": "Configuration for call_auto_reply service type" }, "ServiceConfigCustomTemplateInstance": { "type": "object", "properties": { "template_service_id": { "type": "string", "description": "ID of the service template. The template must be available to the current project or organization." }, "params": { "type": "object", "additionalProperties": true, "description": "Key/value pairs for all service template parameters. If the values satisfy the validation rules specified in the service template, they will also be copied to the `vars` property of the service." } }, "required": [ "template_service_id", "params" ], "description": "Configuration for custom_template_instance service type" }, "MessageBody": { "type": "object", "properties": { "content": { "type": "string", "description": "Text content of the message.", "x-supports-variables": true }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Required unless file_id is provided.\n\n For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. \"data:image/png;base64,...\"), with a maximum decoded file size of 5 MB. When using a data URI, Telerivet will automatically store the file in your project." }, "type": { "type": "string", "description": "MIME type of the media file (e.g., image/jpeg). If not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided." }, "filename": { "type": "string", "description": "Original filename of the media file. Ignored if file_id is provided." }, "size": { "type": "integer", "description": "Size of the media file in bytes." }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable. If file_id is provided, url is not required." } } }, "description": "Array of media attachments." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message. See Route-Specific Parameters.", "x-supports-variables": true }, "track_clicks": { "type": "boolean", "description": "Whether to shorten links and track link clicks in this message." }, "short_link_params": { "type": "object", "properties": { "domain": { "type": "string", "description": "Custom domain for short links. Must be configured for this project." }, "expiration_sec": { "type": "integer", "description": "Expiration time in seconds for short links. Must be positive and less than one year." } }, "description": "Parameters for short links when track_clicks is enabled." } } }, "PollQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the question (alphanumeric, max 15 characters). Used as the variable name for storing responses." }, "question_type": { "type": "string", "description": "Type of question.", "enum": [ "open", "multiple_choice" ] }, "body": { "$ref": "#/components/schemas/MessageBody", "description": "Question message content." }, "content": { "type": "string", "description": "Question text (alternative to body.content for backwards compatibility)." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/PollChoice" }, "description": "Array of response choices (for multiple_choice questions)." }, "none_choice": { "$ref": "#/components/schemas/PollNoneChoice", "description": "Choice for responses that do not match any defined choice (does not have conditions)." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/MessagingPollAction" }, "description": "Array of rule actions to execute after the question is answered. See Actions." }, "timeouts": { "type": "array", "items": { "$ref": "#/components/schemas/PollTimeout" }, "description": "Array of timeout configurations." } }, "required": [ "id", "question_type", "body" ] }, "PollChoice": { "type": "object", "properties": { "code": { "type": "string", "description": "Value stored in the response table when this choice is selected." }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Condition type for matching the response.", "enum": [ "is", "is_not", "has_word", "contains", "does_not_contain", "starts_with", "does_not_start_with", "ends_with", "does_not_end_with", "alpha_before", "alpha_after", "equals", "does_not_equal", "less_than", "greater_than", "less_or_equal", "greater_or_equal" ] }, "value": { "type": "string", "description": "Value to match against the response content." } }, "required": [ "type", "value" ] }, "description": "Array of conditions that match this choice. A response matches if any condition is satisfied." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/MessagingPollAction" }, "description": "Array of rule actions to execute when this choice is selected. See Actions." } } }, "PollNoneChoice": { "type": "object", "properties": { "code": { "type": "string", "description": "Value stored in the response table when no other choice matches." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/MessagingPollAction" }, "description": "Array of rule actions to execute when no other choice matches. See Actions." } } }, "PollTimeout": { "type": "object", "properties": { "schedule": { "type": "object", "properties": { "interval": { "type": "string", "description": "Time interval type.", "enum": [ "minutes", "days" ] }, "minutes": { "type": "number", "description": "Number of minutes (when interval is \"minutes\")." }, "days": { "type": "number", "description": "Number of days (when interval is \"days\")." } }, "required": [ "interval" ], "description": "Timeout schedule configuration." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/MessagingPollAction" }, "description": "Array of rule actions to execute when the timeout occurs. See Actions." } }, "required": [ "schedule" ] }, "VoiceAudio": { "type": "object", "properties": { "mode": { "type": "string", "description": "Audio source mode.", "enum": [ "file", "tts" ] }, "audio_url": { "type": "string", "description": "URL of the audio file to play (WAV or MP3). Required when mode is \"file\"." }, "audio_title": { "type": "string", "description": "Title for the audio file displayed in the web app (not played to the caller). Used when mode is \"file\"." }, "text": { "type": "string", "description": "Text to speak using text-to-speech. Required when mode is \"tts\"." }, "language": { "type": "string", "description": "Language code for text-to-speech (e.g., \"en-US\"). Used when mode is \"tts\"." }, "voice": { "type": "string", "description": "Voice for text-to-speech (e.g., \"man\", \"woman\"). Used when mode is \"tts\"." }, "repeat": { "type": "boolean", "description": "If true, repeat the audio once after a short pause." } }, "required": [ "mode" ] }, "VoicePollQuestion": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the question (alphanumeric, max 15 characters). Used as the variable name for storing responses." }, "question_type": { "type": "string", "description": "Type of voice poll question.", "enum": [ "keypress", "digits", "recording", "open" ] }, "body": { "$ref": "#/components/schemas/VoiceAudio", "description": "Audio to play for the question (file or text-to-speech)." }, "choices": { "type": "array", "items": { "$ref": "#/components/schemas/VoicePollChoice" }, "description": "Array of response choices (for keypress and digits questions)." }, "none_choice": { "$ref": "#/components/schemas/VoicePollNoneChoice", "description": "Choice for responses that do not match any defined choice (does not have conditions)." }, "num_digits": { "type": "integer", "description": "Number of digits to collect (for digits questions, 1-30)." }, "timeout": { "type": "integer", "description": "Timeout in seconds for digit input (for digits questions, 1-600, default 10)." }, "submit_on_hash": { "type": "boolean", "description": "If true, the # key submits the digit input (for digits questions)." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceAction" }, "description": "Array of rule actions to execute after the question is answered. See Actions." }, "timeouts": { "type": "array", "items": { "$ref": "#/components/schemas/PollTimeout" }, "description": "Array of timeout configurations." } }, "required": [ "id", "question_type", "body" ] }, "VoicePollChoice": { "type": "object", "properties": { "code": { "type": "string", "description": "Value stored in the response table when this choice is selected." }, "key": { "type": "string", "description": "Key press that selects this choice (for keypress questions). Valid values: 0-9, *, #." }, "digits": { "type": "string", "description": "Digits value to match (for digits questions)." }, "condition_type": { "type": "string", "description": "Condition type for matching digit input (for digits questions).", "enum": [ "is", "is_not", "has_word", "contains", "does_not_contain", "starts_with", "does_not_start_with", "ends_with", "does_not_end_with", "alpha_before", "alpha_after", "equals", "does_not_equal", "less_than", "greater_than", "less_or_equal", "greater_or_equal" ] }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceAction" }, "description": "Array of rule actions to execute when this choice is selected. See Actions." } } }, "VoicePollNoneChoice": { "type": "object", "properties": { "code": { "type": "string", "description": "Value stored in the response table when no other choice matches." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/VoiceAction" }, "description": "Array of rule actions to execute when no other choice matches. See Actions." } } }, "CreateServiceRequest": { "type": "object", "description": "Request body for POST /v1/projects/{project_id}/services", "properties": { "service_type": { "type": "string", "description": "Type of service to create. See x-service-types in info section for all types and their configurations.", "enum": [ "incoming_message_actions", "contact_actions", "message_actions", "project_actions", "message_status_actions", "voice_actions", "ussd_actions", "data_row_actions", "incoming_message_webhook", "optin_optout", "keyword_auto_reply", "messaging_poll", "voice_poll", "scheduled_actions", "auto_reply", "call_auto_reply", "incoming_message_script", "contact_script", "message_script", "data_row_script", "scheduled_script", "webhook_script", "voice_script", "ussd_script", "project_script", "opt_out_page", "button_page", "custom_template_instance" ] }, "name": { "type": "string", "description": "Name of the service (auto-generated if not provided)" }, "config": { "type": "object", "description": "Configuration specific to the service_type. See x-service-types for required fields per type.", "oneOf": [ { "$ref": "#/components/schemas/ServiceConfigIncomingMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigContactActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageActions" }, { "$ref": "#/components/schemas/ServiceConfigProjectActions" }, { "$ref": "#/components/schemas/ServiceConfigMessageStatusActions" }, { "$ref": "#/components/schemas/ServiceConfigVoiceActions" }, { "$ref": "#/components/schemas/ServiceConfigUssdActions" }, { "$ref": "#/components/schemas/ServiceConfigDataRowActions" }, { "$ref": "#/components/schemas/ServiceConfigIncomingMessageWebhook" }, { "$ref": "#/components/schemas/ServiceConfigOptinOptout" }, { "$ref": "#/components/schemas/ServiceConfigKeywordAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigMessagingPoll" }, { "$ref": "#/components/schemas/ServiceConfigVoicePoll" }, { "$ref": "#/components/schemas/ServiceConfigScheduledActions" }, { "$ref": "#/components/schemas/ServiceConfigAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigCallAutoReply" }, { "$ref": "#/components/schemas/ServiceConfigScript" }, { "$ref": "#/components/schemas/ServiceConfigOptOutPage" }, { "$ref": "#/components/schemas/ServiceConfigButtonPage" }, { "$ref": "#/components/schemas/ServiceConfigCustomTemplateInstance" } ] }, "active": { "type": "boolean", "default": true, "description": "Whether the service is active" }, "vars": { "type": "object", "description": "Custom variables for the service", "additionalProperties": true }, "phone_ids": { "type": "array", "items": { "type": "string" }, "description": "Limit to specific phone/route IDs (null for all)" }, "message_types": { "type": "array", "items": { "type": "string", "enum": [ "text", "call", "sms", "mms", "ussd_session", "chat" ] }, "description": "Message types this service handles. Only applies to services that handle incoming messages." }, "direction": { "type": "string", "enum": [ "incoming", "outgoing", "both" ], "description": "Direction of messages/calls this service handles. Only applies to voice services." }, "table_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of data table IDs that this service applies to. Only applies to data row services. If not specified, the service applies to all data tables." }, "message_statuses": { "type": "array", "items": { "type": "string", "enum": [ "sent", "delivered", "failed", "failed_queued", "not_delivered" ] }, "description": "Array of message statuses to handle. Only applies to message_status_actions service type." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Array of tags for categorizing the service (max 10 tags, max 32 characters each)." }, "priority": { "type": "integer", "description": "Execution priority (lower numbers run first)" } }, "required": [ "service_type", "config" ] }, "ServiceConfigScript": { "type": "object", "properties": { "code": { "type": "string", "description": "JavaScript code to execute (max 100 KB). The code must define a main() function as the entry point, which is automatically called when the service is triggered. The main() function can optionally return a value. To run code longer than 100 KB, use a Cloud Script Module." } }, "required": [ "code" ], "description": "Configuration for Cloud Script services" }, "ServiceConfigIncomingMessageActions": { "type": "object", "description": "Configuration for `incoming_message_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/MessageAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } }, "response_handlers": { "type": "array", "description": "Array of response handler definitions. Response handlers are triggered when the service is waiting for input (e.g., after `wait_response` actions).", "items": { "type": "object", "properties": { "state_id": { "type": "string", "description": "Unique state identifier for this response handler. Must be a valid variable name and cannot be \"initial\"." }, "actions": { "type": "array", "description": "Array of actions to execute when a response is received in this state.", "items": { "$ref": "#/components/schemas/MessageAction" } } }, "required": [ "state_id", "actions" ] } } } }, "ServiceConfigContactActions": { "type": "object", "description": "Configuration for `contact_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/ContactAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } }, "response_handlers": { "type": "array", "description": "Array of response handler definitions. Response handlers are triggered when the service is waiting for input (e.g., after `wait_response` actions).", "items": { "type": "object", "properties": { "state_id": { "type": "string", "description": "Unique state identifier for this response handler. Must be a valid variable name and cannot be \"initial\"." }, "actions": { "type": "array", "description": "Array of actions to execute when a response is received in this state.", "items": { "$ref": "#/components/schemas/MessageAction" } } }, "required": [ "state_id", "actions" ] } } } }, "ServiceConfigMessageActions": { "type": "object", "description": "Configuration for `message_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/MessageAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } }, "response_handlers": { "type": "array", "description": "Array of response handler definitions. Response handlers are triggered when the service is waiting for input (e.g., after `wait_response` actions).", "items": { "type": "object", "properties": { "state_id": { "type": "string", "description": "Unique state identifier for this response handler. Must be a valid variable name and cannot be \"initial\"." }, "actions": { "type": "array", "description": "Array of actions to execute when a response is received in this state.", "items": { "$ref": "#/components/schemas/MessageAction" } } }, "required": [ "state_id", "actions" ] } } } }, "ServiceConfigProjectActions": { "type": "object", "description": "Configuration for `project_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/ProjectAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } } } }, "ServiceConfigMessageStatusActions": { "type": "object", "description": "Configuration for `message_status_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/MessageStatusAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } } } }, "ServiceConfigVoiceActions": { "type": "object", "description": "Configuration for `voice_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/VoiceAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } }, "response_handlers": { "type": "array", "description": "Array of response handler definitions. Response handlers are triggered when the service is waiting for input (e.g., after `prompt_key`, `prompt_digits`, or `record_audio` actions).", "items": { "type": "object", "properties": { "state_id": { "type": "string", "description": "Unique state identifier for this response handler. Must be a valid variable name and cannot be \"initial\"." }, "actions": { "type": "array", "description": "Array of actions to execute when a response is received in this state.", "items": { "$ref": "#/components/schemas/VoiceAction" } } }, "required": [ "state_id", "actions" ] } } } }, "ServiceConfigUssdActions": { "type": "object", "description": "Configuration for `ussd_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/USSDAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } }, "response_handlers": { "type": "array", "description": "Array of response handler definitions. Response handlers are triggered when the service is waiting for input (e.g., after `wait_ussd_response` actions).", "items": { "type": "object", "properties": { "state_id": { "type": "string", "description": "Unique state identifier for this response handler. Must be a valid variable name and cannot be \"initial\"." }, "actions": { "type": "array", "description": "Array of actions to execute when a response is received in this state.", "items": { "$ref": "#/components/schemas/USSDAction" } } }, "required": [ "state_id", "actions" ] } } } }, "ServiceConfigDataRowActions": { "type": "object", "description": "Configuration for `data_row_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/ContactAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } }, "response_handlers": { "type": "array", "description": "Array of response handler definitions. Response handlers are triggered when the service is waiting for input (e.g., after `wait_response` actions).", "items": { "type": "object", "properties": { "state_id": { "type": "string", "description": "Unique state identifier for this response handler. Must be a valid variable name and cannot be \"initial\"." }, "actions": { "type": "array", "description": "Array of actions to execute when a response is received in this state.", "items": { "$ref": "#/components/schemas/MessageAction" } } }, "required": [ "state_id", "actions" ] } } } }, "ServiceConfigScheduledActions": { "type": "object", "description": "Configuration for `scheduled_actions` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/ProjectAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } } } }, "ServiceConfigOptOutPage": { "type": "object", "description": "Configuration for `opt_out_page` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/ButtonPageAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } } } }, "ServiceConfigButtonPage": { "type": "object", "description": "Configuration for `button_page` service type.", "properties": { "actions": { "type": "array", "description": "Array of actions to execute. Each action is an object with a `type` property and additional properties depending on the action type. See Action Reference for documentation of available action types.", "items": { "$ref": "#/components/schemas/ButtonPageAction" } }, "subroutines": { "type": "array", "description": "Array of subroutine definitions. Subroutines are reusable sets of actions that can be called from the main actions or other subroutines.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Unique name for the subroutine (max 32 characters)." }, "context": { "type": "string", "description": "Context type for the subroutine. If not specified, defaults to the service's context." }, "actions": { "type": "array", "description": "Array of actions to execute when the subroutine is called. Available actions depend on the subroutine's context.", "items": { "$ref": "#/components/schemas/Action" } } }, "required": [ "name", "actions" ] } } } }, "ActionAddContactToGroup": { "type": "object", "description": "Adds the current contact to a group. If the group doesn't exist yet, Telerivet will create it.\n\nIf you want to add a contact other than the one who sent the message, add a \"Use another contact\" rule before this rule.", "properties": { "type": { "type": "string", "const": "add_contact_to_group", "description": "Action type identifier" }, "group_name": { "type": "string", "description": "Name of the group. If the group does not exist, it will be created.", "x-supports-variables": true } }, "required": [ "type", "group_name" ], "example": { "type": "add_contact_to_group", "group_name": "subscribers" } }, "ActionAddLabelToMessage": { "type": "object", "description": "Adds a label to the current message. This makes it easy to segment certain types of messages on your Messages page.", "properties": { "type": { "type": "string", "const": "add_label_to_message", "description": "Action type identifier" }, "label_name": { "type": "string", "description": "Name of the label to add to the message.", "x-supports-variables": true } }, "required": [ "type", "label_name" ], "example": { "type": "add_label_to_message", "label_name": "support requests" } }, "ActionBlockContact": { "type": "object", "description": "Blocks the current contact.", "properties": { "type": { "type": "string", "const": "block_contact", "description": "Action type identifier" }, "send_blocked": { "type": "boolean", "description": "If true, block sending messages to this contact. If false, unblock the contact. Default: true." } }, "required": [ "type" ], "example": { "type": "block_contact", "send_blocked": true } }, "ActionCallContact": { "type": "object", "description": "Sends a voice call to the current contact using a specified IVR service.", "properties": { "type": { "type": "string", "const": "call_contact", "description": "Action type identifier" }, "service_id": { "type": "string", "description": "ID of the voice/IVR service to use for the call." }, "route_id": { "type": "string", "description": "ID of the route to use for the call. If not specified, uses the default route." }, "schedule": { "type": "object", "additionalProperties": true, "description": "Schedule for when to make the call. If not specified, calls immediately." } }, "required": [ "type", "service_id" ] }, "ActionCancelScheduledMessages": { "type": "object", "description": "Cancels all scheduled messages to the current contact.\n\nNote this doesn't cancel messages that are scheduled to an entire group. In this case, the contact would need to be removed from the group in order to cancel the message.\n", "properties": { "type": { "type": "string", "const": "cancel_scheduled_messages", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "cancel_scheduled_messages" } }, "ActionCondition": { "type": "object", "description": "\nA rule that only matches if a certain condition is true (e.g. the message has a particular keyword or sender). Always combined with one or more other rules.\n\n\"If ... then ...\" rules can use the following types of conditions:\n\n* is\n* is not\n* has word\n* does not have word\n* contains\n* does not contain\n* starts with\n* does not start with\n* ends with\n* does not end with\n* alphabetically before\n* alphabetically after\n* equals\n* does not equal\n* less than\n* greater than\n* less than or equal to\n* greater than or equal to\n* contact is in group\n* contact is not in group\n\nA single \"If ... then ...\" rule can contain multiple conditions, joined together with either 'and' or 'or'.", "properties": { "type": { "type": "string", "const": "condition", "description": "Action type identifier" }, "conditions": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Condition type. Values: is, is_not, has_word, contains, does_not_contain, starts_with, does_not_start_with, ends_with, does_not_end_with, alpha_before, alpha_after, equals, does_not_equal, less_than, greater_than, less_or_equal, greater_or_equal, contact_is_in_group, contact_not_in_group." }, "variable": { "type": "string", "description": "Variable to test, e.g. [[word1]], [[contact.name]]. Not required for contact_is_in_group and contact_not_in_group conditions." }, "value": { "type": "string", "description": "Value to compare against (or group name for group membership conditions)." } }, "required": [ "type", "variable", "value" ] }, "description": "Array of condition objects. Required unless if_mode is else." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Action" }, "description": "Array of actions to execute if the conditions match." }, "op": { "type": "string", "description": "Operator to join multiple conditions. Values: and (all conditions must match), or (any condition must match). Default: or." }, "if_mode": { "type": "string", "description": "Controls how this condition relates to previous conditions. Values: if (default, starts a new conditional block), else_if (only evaluated if the previous if or else_if did not match), else (executed if none of the previous if/else_if conditions matched; does not require conditions array)." } }, "required": [ "type", "actions" ] }, "ActionCopyMessageToProject": { "type": "object", "description": "Copies the current incoming message to another project within the same organization.\n\nThis is useful for routing messages to different projects based on message content or contact information, while keeping the original message in the current project.", "properties": { "type": { "type": "string", "const": "copy_message_to_project", "description": "Action type identifier" }, "project_id": { "type": "string", "description": "ID of the project to copy the message to. Must be a project within the same organization.", "x-supports-variables": true } }, "required": [ "type", "project_id" ], "example": { "type": "copy_message_to_project", "project_id": "PJxxxxxxxxxxxxxxxx" } }, "ActionEndSession": { "type": "object", "description": "Ends the current USSD session.", "properties": { "type": { "type": "string", "const": "end_session", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "end_session" } }, "ActionEndSurvey": { "type": "object", "description": "Within a poll service, skips to the end of the survey.", "properties": { "type": { "type": "string", "const": "end_survey", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "end_survey" } }, "ActionForwardCall": { "type": "object", "description": "Forwards the incoming call to another phone number.", "properties": { "type": { "type": "string", "const": "forward_call", "description": "Action type identifier" }, "phone_number": { "type": "string", "description": "Phone number to forward the call to.", "x-supports-variables": true } }, "required": [ "type", "phone_number" ], "example": { "type": "forward_call", "phone_number": "+16505550123" } }, "ActionHangup": { "type": "object", "description": "Hangs up the phone call.", "properties": { "type": { "type": "string", "const": "hangup", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "hangup" } }, "ActionIgnoreMessage": { "type": "object", "description": "Within a poll service, ignores the current message.", "properties": { "type": { "type": "string", "const": "ignore_message", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "ignore_message" } }, "ActionLog": { "type": "object", "description": "Adds a log message to Telerivet's [service log](/dashboard/service_logs).\n\nTo view the service log, open your [Services page](/dashboard/services) and click More > View logs.\n\nWhen using the \"Test Service\" feature, log messages will be displayed directly in the simulated phone dialog.\n", "properties": { "type": { "type": "string", "const": "log", "description": "Action type identifier" }, "value": { "type": "string", "description": "Log message content.", "x-supports-variables": true } }, "required": [ "type", "value" ], "example": { "type": "log", "value": "word1 = [[word1]]" } }, "ActionPlayAudio": { "type": "object", "description": "Plays an audio file in WAV or MP3 format in the voice call, which may be uploaded, linked, or recorded via the Telerivet web app. Alternatively, can use text-to-speech to speak a message.", "properties": { "type": { "type": "string", "const": "play_audio", "description": "Action type identifier" }, "mode": { "type": "string", "description": "Audio source mode.", "enum": [ "file", "tts" ] }, "audio_url": { "type": "string", "description": "URL of the audio file to play (WAV or MP3). Required when mode is \"file\".", "x-supports-variables": true }, "audio_title": { "type": "string", "description": "Title for the audio file displayed in the web app (not played to the caller). Used when mode is \"file\"." }, "text": { "type": "string", "description": "Text to speak using text-to-speech. Required when mode is \"tts\". If mode is \"file\", the text is not used in the actual call but is displayed as the transcript of the file within the web app.", "x-supports-variables": true }, "language": { "type": "string", "description": "Language code for text-to-speech (e.g., \"en-US\"). Used when mode is \"tts\"." }, "voice": { "type": "string", "description": "Voice for text-to-speech (e.g., \"man\", \"woman\"). Used when mode is \"tts\"." }, "repeat": { "type": "boolean", "description": "If true, repeat the audio once after a short pause." } }, "required": [ "type", "mode" ], "example": { "type": "play_audio", "mode": "file", "audio_url": "http://localhost/_media/sounds/bell2.mp3" } }, "ActionPushToHubspot": { "type": "object", "description": "Pushes the message to a HubSpot Help Desk inbox, in a conversation associated with the current contact. HubSpot agents can reply directly to send a reply to the contact.", "properties": { "type": { "type": "string", "const": "push_to_hubspot", "description": "Action type identifier" }, "integration_id": { "type": "string", "description": "ID of the HubSpot channel integration config." }, "content": { "type": "string", "description": "Content of the message pushed to HubSpot.", "x-supports-variables": true } }, "required": [ "type", "integration_id" ], "example": { "type": "push_to_hubspot", "integration_id": null, "content": "[[content]]" } }, "ActionPushToZendesk": { "type": "object", "description": "Pushes the message to a Zendesk support inbox, in a ticket associated with the current contact. Zendesk agents can reply directly to the Zendesk ticket to send a reply to the contact.", "properties": { "type": { "type": "string", "const": "push_to_zendesk", "description": "Action type identifier" }, "subdomain": { "type": "string", "description": "Zendesk subdomain (e.g., \"example\" for example.zendesk.com)." }, "subject": { "type": "string", "description": "Subject line for the Zendesk ticket.", "x-supports-variables": true }, "content": { "type": "string", "description": "Content of the Zendesk ticket.", "x-supports-variables": true } }, "required": [ "type", "subdomain", "subject", "content" ], "example": { "type": "push_to_zendesk", "subdomain": "example", "subject": "Message from [[contact.name]]", "content": "[[content]]" } }, "ActionRecordAudio": { "type": "object", "description": "Records an audio response from the caller, saves the recording URL as a custom variable on the message, then triggers the associated response handler.", "properties": { "type": { "type": "string", "const": "record_audio", "description": "Action type identifier" }, "state_id": { "type": "string", "description": "ID of the response handler that will be triggered when the recording is received (e.g., \"recording\"). Also used as the name of the variable where the recording URL will be stored (e.g. [[vars.recording]])." } }, "required": [ "type", "state_id" ], "example": { "type": "record_audio", "state_id": "input" } }, "ActionRemoveContactFromGroup": { "type": "object", "description": "Removes the current contact from a group.\n\nIf you want to remove a contact other than the one who sent the message, add a \"Use another contact\" rule before this rule.", "properties": { "type": { "type": "string", "const": "remove_contact_from_group", "description": "Action type identifier" }, "group_name": { "type": "string", "description": "Name of the group. If the group does not exist, it will be created.", "x-supports-variables": true } }, "required": [ "type", "group_name" ], "example": { "type": "remove_contact_from_group", "group_name": "subscribers" } }, "ActionRepeatQuestion": { "type": "object", "description": "Within a poll service, repeats the current question again.", "properties": { "type": { "type": "string", "const": "repeat_question", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "repeat_question" } }, "ActionReply": { "type": "object", "description": "Sends a text reply to the sender.\n\nOptionally, the reply can be scheduled after a predefined delay, or sent via a different phone than the one that received the message.", "properties": { "type": { "type": "string", "const": "reply", "description": "Action type identifier" }, "body": { "$ref": "#/components/schemas/MessageBody", "description": "Message body." }, "route_id": { "type": "string", "description": "ID of the route to send the message from. If not specified, uses the default route." }, "label_names": { "type": "array", "items": { "type": "string" }, "description": "Array of label names to apply to the sent message.", "x-supports-variables": true }, "schedule": { "type": "object", "additionalProperties": true, "description": "Schedule to send the message at a later time." } }, "required": [ "type", "body" ], "example": { "type": "reply", "body": { "content": "Hello, [[contact.name]]." } } }, "ActionReplySimple": { "type": "object", "description": "Sends a text reply to the sender (simple version without labels, schedule, or route configuration).", "properties": { "type": { "type": "string", "const": "reply_simple", "description": "Action type identifier" }, "body": { "$ref": "#/components/schemas/MessageBody", "description": "Message body." }, "schedule": { "type": "object", "additionalProperties": true, "description": "Schedule to send the message at a later time." } }, "required": [ "type", "body" ], "example": { "type": "reply_simple", "body": { "content": "Hello, [[contact.name]]." } } }, "ActionResendMessage": { "type": "object", "description": "Within a service triggered when a message status changes, will automatically resend the current message via the same route or a different route.", "properties": { "type": { "type": "string", "const": "resend_message", "description": "Action type identifier" }, "route_id": { "type": "string", "description": "ID of the route to resend the message from. If not specified, uses the original route." }, "schedule": { "type": "object", "additionalProperties": true, "description": "Schedule for when to resend the message. If not specified, resends immediately." } }, "required": [ "type" ], "example": { "type": "resend_message" } }, "ActionRunScript": { "type": "object", "description": "Runs custom JavaScript code on Telerivet's servers using Telerivet's Cloud Script API.\n\nThis makes it possible to define custom actions such as calling the Telerivet REST API or third-party APIs, or parsing structured data from incoming messages.\n\nFor more details, see the [Cloud Script API documentation](/api/script).\n", "properties": { "type": { "type": "string", "const": "run_script", "description": "Action type identifier" }, "code": { "type": "string", "description": "JavaScript code to execute. See Cloud Script API for available functions and variables." } }, "required": [ "type", "code" ], "example": { "type": "run_script", "code": "var response = httpClient.request(\n \"http://api.coindesk.com/v1/bpi/currentprice.json\");\n\nvar bitcoinInfo = JSON.parse(response.content);\nsendReply(\"1 BTC = $\" + bitcoinInfo.bpi.USD.rate);" } }, "ActionRunSubroutine": { "type": "object", "description": "Triggers a set of actions which can be reused multiple times in the same service.", "properties": { "type": { "type": "string", "const": "run_subroutine", "description": "Action type identifier" }, "name": { "type": "string", "description": "Name of the subroutine to run." } }, "required": [ "type", "name" ] }, "ActionSendAirtime": { "type": "object", "description": "Sends airtime to the current contact if they are on a particular mobile network. Acts like a condition, and allows running other actions if the contact is on one of the supported networks. An 'else' condition can be added below this action to handle contacts that are not on the supported mobile networks.", "properties": { "type": { "type": "string", "const": "send_airtime", "description": "Action type identifier" }, "provider_id": { "type": "string", "description": "ID of the airtime provider to use." }, "products": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string", "description": "Two-letter country code (e.g., KE for Kenya)." }, "operator_id": { "type": "string", "description": "ID of the mobile network operator (according to the airtime provider). Required if the provider supports multiple operators." }, "product_id": { "type": "string", "description": "ID of the airtime product to send (according to the airtime provider)." }, "amount": { "type": "number", "description": "Amount of airtime to send. Required for variable-amount products." } }, "required": [ "country", "product_id" ] }, "description": "Array of product configurations for different mobile networks or countries." }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/Action" }, "description": "Array of actions to execute if the contact is on a supported mobile network." }, "on_success": { "type": "string", "description": "Name of subroutine to execute when the airtime transaction succeeds." }, "on_failure": { "type": "string", "description": "Name of subroutine to execute when the airtime transaction fails." } }, "required": [ "type", "provider_id", "products" ] }, "ActionSendEmail": { "type": "object", "description": "Sends a plain-text email with custom subject line and body.\n\nEach rule can only send to a single email address; if you need multiple recipients, we recommend setting up a mailing list on your own server.\n\nWhen receiving MMS and chat messages, you can optionally send the multimedia files as email attachments.\n\nTo prevent abuse, it isn't possible to change the 'From' name or email address of the email, although these settings can be configured when using Telerivet on a custom domain.", "properties": { "type": { "type": "string", "const": "send_email", "description": "Action type identifier" }, "to_email": { "type": "string", "description": "Recipient email address.", "x-supports-variables": true }, "subject": { "type": "string", "description": "Email subject line.", "x-supports-variables": true }, "body_text": { "type": "string", "description": "Email body text.", "x-supports-variables": true }, "reply_to": { "type": "string", "description": "Reply-to email address.", "x-supports-variables": true }, "include_message_attachments": { "type": "boolean", "description": "If true, include any attachments from the current message as email attachments." } }, "required": [ "type", "to_email", "subject", "body_text" ], "example": { "type": "send_email", "to_email": "admin@example.com", "subject": "New message from [[contact.name]]", "body_text": "Phone Number: [[from_number]]\n\n[[content]]" } }, "ActionSendText": { "type": "object", "description": "Sends a text message to any phone number.\n\nOptionally, the message can be scheduled after a predefined delay, or sent via a different phone than the one that received the message.", "properties": { "type": { "type": "string", "const": "send_text", "description": "Action type identifier" }, "body": { "$ref": "#/components/schemas/MessageBody", "description": "Message body." }, "route_id": { "type": "string", "description": "ID of the route to send the message from. If not specified, uses the default route." }, "label_names": { "type": "array", "items": { "type": "string" }, "description": "Array of label names to apply to the sent message.", "x-supports-variables": true }, "schedule": { "type": "object", "additionalProperties": true, "description": "Schedule to send the message at a later time." }, "to_number": { "type": "string", "description": "Phone number to send the message to.", "x-supports-variables": true } }, "required": [ "type", "body", "to_number" ], "example": { "type": "send_text", "body": { "content": "[[contact.name]] sent you a message: [[content]]." }, "to_number": "+16505550123" } }, "ActionSendTextToContact": { "type": "object", "description": "Sends a text message to the current contact.", "properties": { "type": { "type": "string", "const": "send_text_to_contact", "description": "Action type identifier" }, "body": { "$ref": "#/components/schemas/MessageBody", "description": "Message body." }, "route_id": { "type": "string", "description": "ID of the route to send the message from. If not specified, uses the default route." }, "label_names": { "type": "array", "items": { "type": "string" }, "description": "Array of label names to apply to the sent message.", "x-supports-variables": true }, "schedule": { "type": "object", "additionalProperties": true, "description": "Schedule to send the message at a later time." } }, "required": [ "type", "body" ], "example": { "type": "send_text_to_contact", "body": { "content": "Hello, [[contact.name]]." } } }, "ActionSendTextToGroup": { "type": "object", "description": "Sends a SMS message to a group defined on your Contacts page.\n\nOptionally, you can exclude the message sender from receiving the message (common when implementing a group chat system).", "properties": { "type": { "type": "string", "const": "send_text_to_group", "description": "Action type identifier" }, "body": { "$ref": "#/components/schemas/MessageBody", "description": "Message body." }, "route_id": { "type": "string", "description": "ID of the route to send the message from. If not specified, uses the default route." }, "label_names": { "type": "array", "items": { "type": "string" }, "description": "Array of label names to apply to the sent message.", "x-supports-variables": true }, "schedule": { "type": "object", "additionalProperties": true, "description": "Schedule to send the message at a later time." }, "group_name": { "type": "string", "description": "Name of the group to send the message to.", "x-supports-variables": true }, "exclude_sender": { "type": "boolean", "description": "If true, exclude the message sender from receiving the group message." } }, "required": [ "type", "body", "group_name" ], "example": { "type": "send_text_to_group", "body": { "content": "[[contact.name]] said: [[content]]." }, "group_name": "subscribers", "exclude_sender": null } }, "ActionSendUssd": { "type": "object", "description": "Sends a USSD request from your Android phone to your mobile network.\n\nOn some mobile networks, USSD requests can be used to check your airtime balance, transfer airtime to other phone numbers, and more.\n\nNote that this requires a compatible Android phone running the Telerivet Gateway app. Also, Telerivet cannot automatically invoke USSD requests that return menus or prompts.", "properties": { "type": { "type": "string", "const": "send_ussd", "description": "Action type identifier" }, "mmi_code": { "type": "string", "description": "USSD/MMI code to send (e.g. *123#).", "x-supports-variables": true }, "route_id": { "type": "string", "description": "ID of the route to send the USSD request from. If not specified, uses the default route." } }, "required": [ "type", "mmi_code" ], "example": { "type": "send_ussd", "mmi_code": "*104*1000*[[from_number.national_raw]]#" } }, "ActionSendUssdReply": { "type": "object", "description": "Shows the specified text in the active USSD session. If this action is followed by a 'Wait for response' action, the text will be displayed as part of a USSD prompt.", "properties": { "type": { "type": "string", "const": "send_ussd_reply", "description": "Action type identifier" }, "text": { "type": "string", "description": "Text to display in the USSD session.", "x-supports-variables": true } }, "required": [ "type", "text" ], "example": { "type": "send_ussd_reply", "text": "Please enter a response on the keypad." } }, "ActionSetContact": { "type": "object", "description": "Creates or retrieves a contact with a particular phone number, and sets that as the \"current\" contact for subsequent rules.\n\nThis rule is often used to allow your organization's workers to register other people via SMS, and is typically combined with other rules to add the contact to a group and update their contact information.", "properties": { "type": { "type": "string", "const": "set_contact", "description": "Action type identifier" }, "phone_number": { "type": "string", "description": "Phone number for the contact to use.", "x-supports-variables": true } }, "required": [ "type", "phone_number" ], "example": { "type": "set_contact", "phone_number": "[[word2]]" } }, "ActionSetContactName": { "type": "object", "description": "Updates the name of the current contact in Telerivet.", "properties": { "type": { "type": "string", "const": "set_contact_name", "description": "Action type identifier" }, "name": { "type": "string", "description": "Name to assign to the contact.", "x-supports-variables": true } }, "required": [ "type", "name" ], "example": { "type": "set_contact_name", "name": "[[word3]]" } }, "ActionSetContactVar": { "type": "object", "description": "Updates custom contact information for the current contact (for example, email address or birthdate).\n\nThe rules editor lists the current variable names available for your project. You can also use a new variable name consisting of letters, numbers, and underscores.", "properties": { "type": { "type": "string", "const": "set_contact_var", "description": "Action type identifier" }, "variable": { "type": "string", "description": "Name of the contact variable to set (without the contact.vars prefix)." }, "value": { "type": "string", "description": "Value to assign to the variable.", "x-supports-variables": true } }, "required": [ "type", "variable" ], "example": { "type": "set_contact_var", "variable": "email", "value": "[[word4]]" } }, "ActionSetMessageVar": { "type": "object", "description": "Updates a custom variable for the current message.\n\nWhen triggered from a service that has a response data table (such as a poll service or custom actions with response handlers), custom message variables set via this action are automatically copied as custom variables on the corresponding response data table row. This is the recommended way to store derived or computed values in the response data table.", "properties": { "type": { "type": "string", "const": "set_message_var", "description": "Action type identifier" }, "variable": { "type": "string", "description": "Name of the message variable to set (without the vars prefix)." }, "value": { "type": "string", "description": "Value to assign to the variable.", "x-supports-variables": true } }, "required": [ "type", "variable" ], "example": { "type": "set_message_var", "variable": "urgent", "value": "yes" } }, "ActionSetVariable": { "type": "object", "description": "Updates the value of any writable variable within the Rules Engine.\n\nOptionally, you can use this rule to perform simple numeric operations between two variables such as addition, subtraction, multiplication and division.\n\nRead-only variables cannot be updated via this rule.\n\n[See available variables](#message_variables)", "properties": { "type": { "type": "string", "const": "set_variable", "description": "Action type identifier" }, "variable": { "type": "string", "description": "Name of the variable to set (e.g. $foo, contact.vars.bar, phone.vars.baz)." }, "value": { "type": "string", "description": "Value to assign to the variable.", "x-supports-variables": true }, "op": { "type": "string", "description": "Optional arithmetic operation to perform between value and value2.", "enum": [ "plus", "minus", "times", "div" ] }, "value2": { "type": "string", "description": "Second operand for the arithmetic operation (required if op is specified).", "x-supports-variables": true } }, "required": [ "type", "variable", "value" ], "example": { "type": "set_variable", "variable": "$foo", "value": "[[word1]]" } }, "ActionSkipToQuestion": { "type": "object", "description": "Within a poll service, skips to a question outside the normal order.", "properties": { "type": { "type": "string", "const": "skip_to_question", "description": "Action type identifier" }, "question_id": { "type": "string", "description": "ID of the poll question to skip to.", "x-supports-variables": true } }, "required": [ "type", "question_id" ], "example": { "type": "skip_to_question", "question_id": "q3" } }, "ActionStarMessage": { "type": "object", "description": "Adds a star to the current message. This makes it easy to segment important messages on your Messages page.", "properties": { "type": { "type": "string", "const": "star_message", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "star_message" } }, "ActionStop": { "type": "object", "description": "Stops processing rules for this message (for this service only).", "properties": { "type": { "type": "string", "const": "stop", "description": "Action type identifier" } }, "required": [ "type" ], "example": { "type": "stop" } }, "ActionTriggerContactService": { "type": "object", "description": "Triggers another service for the current contact.", "properties": { "type": { "type": "string", "const": "trigger_contact_service", "description": "Action type identifier" }, "service_id": { "type": "string", "description": "ID of the service to trigger." } }, "required": [ "type", "service_id" ] }, "ActionTriggerMessageService": { "type": "object", "description": "Triggers another service for the current message.", "properties": { "type": { "type": "string", "const": "trigger_message_service", "description": "Action type identifier" }, "service_id": { "type": "string", "description": "ID of the service to trigger." } }, "required": [ "type", "service_id" ] }, "ActionTriggerProjectService": { "type": "object", "description": "Triggers another service for the current project.", "properties": { "type": { "type": "string", "const": "trigger_project_service", "description": "Action type identifier" }, "service_id": { "type": "string", "description": "ID of the service to trigger." } }, "required": [ "type", "service_id" ] }, "ActionUsePhone": { "type": "object", "description": "Within a custom route, selects one or more basic routes that can be used to send the message.", "properties": { "type": { "type": "string", "const": "use_phone", "description": "Action type identifier" }, "phone_ids": { "type": "array", "items": { "type": "string" }, "description": "Array of basic route IDs that can be used to send the message" } }, "required": [ "type", "phone_ids" ], "example": { "type": "use_phone", "phone_ids": [ "PN123abc", "PN456def" ] } }, "ActionWaitForDigits": { "type": "object", "description": "Waits for the caller to enter digits on the keypad, saves the input as a custom variable on the message, then triggers the associated response handler.", "properties": { "type": { "type": "string", "const": "wait_for_digits", "description": "Action type identifier" }, "state_id": { "type": "string", "description": "ID of the response handler that will be triggered when the response is received (e.g., \"input\"). Also used as the name of the variable where the entered digits will be stored (e.g. [[vars.input]]." }, "max_digits": { "type": "number", "description": "Maximum number of digits to wait for." }, "timeout": { "type": "number", "description": "Number of seconds to wait after the last key press. Default: 10." }, "submit_on_hash": { "type": "boolean", "description": "If true, submit the input when the caller presses #." } }, "required": [ "type", "state_id", "max_digits" ], "example": { "type": "wait_for_digits", "state_id": "input", "max_digits": 4 } }, "ActionWaitForKey": { "type": "object", "description": "Waits for the caller to press a single key on the keypad, saves the input as a custom variable on the message, then triggers the associated response handler.", "properties": { "type": { "type": "string", "const": "wait_for_key", "description": "Action type identifier" }, "state_id": { "type": "string", "description": "ID of the response handler that will be triggered when the key is pressed (e.g., \"input\"). Also used as the name of the variable where the pressed key will be stored (e.g. [[vars.input]])." } }, "required": [ "type", "state_id" ], "example": { "type": "wait_for_key", "state_id": "input" } }, "ActionWaitResponse": { "type": "object", "description": "Waits for a response from the current contact, then processes the response using another set of actions or conditions. Useful for back-and-forth conversations or data collection that requires the contact to send multiple messages.", "properties": { "type": { "type": "string", "const": "wait_response", "description": "Action type identifier" }, "state_id": { "type": "string", "description": "ID of the response handler to process the contact's response." }, "timeout": { "type": "object", "additionalProperties": true, "description": "Schedule for response timeout." } }, "required": [ "type", "state_id" ] }, "ActionWaitUssdResponse": { "type": "object", "description": "Prompts the user for input in the active USSD session, saves the response as a custom variable on the message, and triggers the associated response handler.", "properties": { "type": { "type": "string", "const": "wait_ussd_response", "description": "Action type identifier" }, "state_id": { "type": "string", "description": "ID of the response handler that will be triggered when the response is received (e.g., \"input\"). Also used as the name of the variable where the USSD response will be stored (e.g. [[vars.input]])." } }, "required": [ "type", "state_id" ], "example": { "type": "wait_ussd_response", "state_id": "input" } }, "ActionWebhook": { "type": "object", "description": "Makes a HTTP POST request to a URL on your server, passing several POST parameters with information about the current message and contact.\n\nYour webhook script may optionally return a JSON response with a 'messages' property containing an array of messages to send, and a 'variables' property containing variable names and values to update.\n\nFor details, see the [Webhook API documentation](/api/webhook).", "properties": { "type": { "type": "string", "const": "webhook", "description": "Action type identifier" }, "url": { "type": "string", "description": "Webhook URL to receive the HTTP POST request." }, "secret": { "type": "string", "description": "Secret string passed as POST parameter for request verification." } }, "required": [ "type", "url" ], "example": { "type": "webhook", "url": "http://www.example.com/incoming.php", "secret": "abcdefg" } }, "Action": { "type": "object", "description": "An action in a Custom Actions service. The `type` property determines which action is performed and what additional properties are available. See [Rules Engine Actions](/api/rules_engine#actions) for detailed documentation.", "discriminator": { "propertyName": "type", "mapping": { "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "add_label_to_message": "#/components/schemas/ActionAddLabelToMessage", "block_contact": "#/components/schemas/ActionBlockContact", "call_contact": "#/components/schemas/ActionCallContact", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "condition": "#/components/schemas/ActionCondition", "copy_message_to_project": "#/components/schemas/ActionCopyMessageToProject", "end_session": "#/components/schemas/ActionEndSession", "end_survey": "#/components/schemas/ActionEndSurvey", "forward_call": "#/components/schemas/ActionForwardCall", "hangup": "#/components/schemas/ActionHangup", "ignore_message": "#/components/schemas/ActionIgnoreMessage", "log": "#/components/schemas/ActionLog", "play_audio": "#/components/schemas/ActionPlayAudio", "push_to_hubspot": "#/components/schemas/ActionPushToHubspot", "push_to_zendesk": "#/components/schemas/ActionPushToZendesk", "record_audio": "#/components/schemas/ActionRecordAudio", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "repeat_question": "#/components/schemas/ActionRepeatQuestion", "reply": "#/components/schemas/ActionReply", "reply_simple": "#/components/schemas/ActionReplySimple", "resend_message": "#/components/schemas/ActionResendMessage", "run_script": "#/components/schemas/ActionRunScript", "run_subroutine": "#/components/schemas/ActionRunSubroutine", "send_airtime": "#/components/schemas/ActionSendAirtime", "send_email": "#/components/schemas/ActionSendEmail", "send_text": "#/components/schemas/ActionSendText", "send_text_to_contact": "#/components/schemas/ActionSendTextToContact", "send_text_to_group": "#/components/schemas/ActionSendTextToGroup", "send_ussd": "#/components/schemas/ActionSendUssd", "send_ussd_reply": "#/components/schemas/ActionSendUssdReply", "set_contact": "#/components/schemas/ActionSetContact", "set_contact_name": "#/components/schemas/ActionSetContactName", "set_contact_var": "#/components/schemas/ActionSetContactVar", "set_message_var": "#/components/schemas/ActionSetMessageVar", "set_variable": "#/components/schemas/ActionSetVariable", "skip_to_question": "#/components/schemas/ActionSkipToQuestion", "star_message": "#/components/schemas/ActionStarMessage", "stop": "#/components/schemas/ActionStop", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_message_service": "#/components/schemas/ActionTriggerMessageService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService", "use_phone": "#/components/schemas/ActionUsePhone", "wait_for_digits": "#/components/schemas/ActionWaitForDigits", "wait_for_key": "#/components/schemas/ActionWaitForKey", "wait_response": "#/components/schemas/ActionWaitResponse", "wait_ussd_response": "#/components/schemas/ActionWaitUssdResponse", "webhook": "#/components/schemas/ActionWebhook" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionCallContact" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, { "$ref": "#/components/schemas/ActionEndSession" }, { "$ref": "#/components/schemas/ActionEndSurvey" }, { "$ref": "#/components/schemas/ActionForwardCall" }, { "$ref": "#/components/schemas/ActionHangup" }, { "$ref": "#/components/schemas/ActionIgnoreMessage" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionPlayAudio" }, { "$ref": "#/components/schemas/ActionPushToHubspot" }, { "$ref": "#/components/schemas/ActionPushToZendesk" }, { "$ref": "#/components/schemas/ActionRecordAudio" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionRepeatQuestion" }, { "$ref": "#/components/schemas/ActionReply" }, { "$ref": "#/components/schemas/ActionReplySimple" }, { "$ref": "#/components/schemas/ActionResendMessage" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionRunSubroutine" }, { "$ref": "#/components/schemas/ActionSendAirtime" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendTextToContact" }, { "$ref": "#/components/schemas/ActionSendTextToGroup" }, { "$ref": "#/components/schemas/ActionSendUssd" }, { "$ref": "#/components/schemas/ActionSendUssdReply" }, { "$ref": "#/components/schemas/ActionSetContact" }, { "$ref": "#/components/schemas/ActionSetContactName" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionSetMessageVar" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionSkipToQuestion" }, { "$ref": "#/components/schemas/ActionStarMessage" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerMessageService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" }, { "$ref": "#/components/schemas/ActionUsePhone" }, { "$ref": "#/components/schemas/ActionWaitForDigits" }, { "$ref": "#/components/schemas/ActionWaitForKey" }, { "$ref": "#/components/schemas/ActionWaitResponse" }, { "$ref": "#/components/schemas/ActionWaitUssdResponse" }, { "$ref": "#/components/schemas/ActionWebhook" } ] }, "MessageAction": { "type": "object", "description": "An action available for `incoming_message_actions` and `message_actions` service types.", "discriminator": { "propertyName": "type", "mapping": { "reply": "#/components/schemas/ActionReply", "send_text": "#/components/schemas/ActionSendText", "send_text_to_group": "#/components/schemas/ActionSendTextToGroup", "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "set_contact": "#/components/schemas/ActionSetContact", "set_contact_name": "#/components/schemas/ActionSetContactName", "set_contact_var": "#/components/schemas/ActionSetContactVar", "block_contact": "#/components/schemas/ActionBlockContact", "send_email": "#/components/schemas/ActionSendEmail", "send_airtime": "#/components/schemas/ActionSendAirtime", "add_label_to_message": "#/components/schemas/ActionAddLabelToMessage", "star_message": "#/components/schemas/ActionStarMessage", "set_variable": "#/components/schemas/ActionSetVariable", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "run_script": "#/components/schemas/ActionRunScript", "condition": "#/components/schemas/ActionCondition", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_message_service": "#/components/schemas/ActionTriggerMessageService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService", "stop": "#/components/schemas/ActionStop", "copy_message_to_project": "#/components/schemas/ActionCopyMessageToProject", "set_message_var": "#/components/schemas/ActionSetMessageVar", "wait_response": "#/components/schemas/ActionWaitResponse", "send_ussd": "#/components/schemas/ActionSendUssd", "run_subroutine": "#/components/schemas/ActionRunSubroutine", "call_contact": "#/components/schemas/ActionCallContact", "push_to_zendesk": "#/components/schemas/ActionPushToZendesk", "push_to_hubspot": "#/components/schemas/ActionPushToHubspot" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionReply" }, { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendTextToGroup" }, { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionSetContact" }, { "$ref": "#/components/schemas/ActionSetContactName" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSendAirtime" }, { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, { "$ref": "#/components/schemas/ActionStarMessage" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerMessageService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, { "$ref": "#/components/schemas/ActionSetMessageVar" }, { "$ref": "#/components/schemas/ActionWaitResponse" }, { "$ref": "#/components/schemas/ActionSendUssd" }, { "$ref": "#/components/schemas/ActionRunSubroutine" }, { "$ref": "#/components/schemas/ActionCallContact" }, { "$ref": "#/components/schemas/ActionPushToZendesk" }, { "$ref": "#/components/schemas/ActionPushToHubspot" } ] }, "ContactAction": { "type": "object", "description": "An action available for `contact_actions` and `data_row_actions` service types.", "discriminator": { "propertyName": "type", "mapping": { "send_text_to_contact": "#/components/schemas/ActionSendTextToContact", "send_text": "#/components/schemas/ActionSendText", "send_airtime": "#/components/schemas/ActionSendAirtime", "call_contact": "#/components/schemas/ActionCallContact", "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "set_contact_var": "#/components/schemas/ActionSetContactVar", "block_contact": "#/components/schemas/ActionBlockContact", "send_ussd": "#/components/schemas/ActionSendUssd", "send_email": "#/components/schemas/ActionSendEmail", "set_variable": "#/components/schemas/ActionSetVariable", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "run_script": "#/components/schemas/ActionRunScript", "condition": "#/components/schemas/ActionCondition", "stop": "#/components/schemas/ActionStop", "wait_response": "#/components/schemas/ActionWaitResponse", "run_subroutine": "#/components/schemas/ActionRunSubroutine", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService", "set_contact": "#/components/schemas/ActionSetContact" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionSendTextToContact" }, { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendAirtime" }, { "$ref": "#/components/schemas/ActionCallContact" }, { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionSendUssd" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionWaitResponse" }, { "$ref": "#/components/schemas/ActionRunSubroutine" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" }, { "$ref": "#/components/schemas/ActionSetContact" } ] }, "ProjectAction": { "type": "object", "description": "An action available for `project_actions` and `scheduled_actions` service types.", "discriminator": { "propertyName": "type", "mapping": { "send_text": "#/components/schemas/ActionSendText", "send_text_to_group": "#/components/schemas/ActionSendTextToGroup", "send_ussd": "#/components/schemas/ActionSendUssd", "send_email": "#/components/schemas/ActionSendEmail", "set_variable": "#/components/schemas/ActionSetVariable", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "run_script": "#/components/schemas/ActionRunScript", "condition": "#/components/schemas/ActionCondition", "stop": "#/components/schemas/ActionStop", "run_subroutine": "#/components/schemas/ActionRunSubroutine", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendTextToGroup" }, { "$ref": "#/components/schemas/ActionSendUssd" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionRunSubroutine" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" } ] }, "MessageStatusAction": { "type": "object", "description": "An action available for `message_status_actions` service type.", "discriminator": { "propertyName": "type", "mapping": { "resend_message": "#/components/schemas/ActionResendMessage", "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "set_contact_var": "#/components/schemas/ActionSetContactVar", "block_contact": "#/components/schemas/ActionBlockContact", "send_email": "#/components/schemas/ActionSendEmail", "add_label_to_message": "#/components/schemas/ActionAddLabelToMessage", "star_message": "#/components/schemas/ActionStarMessage", "set_variable": "#/components/schemas/ActionSetVariable", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "condition": "#/components/schemas/ActionCondition", "stop": "#/components/schemas/ActionStop", "copy_message_to_project": "#/components/schemas/ActionCopyMessageToProject", "set_message_var": "#/components/schemas/ActionSetMessageVar", "run_subroutine": "#/components/schemas/ActionRunSubroutine", "run_script": "#/components/schemas/ActionRunScript", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_message_service": "#/components/schemas/ActionTriggerMessageService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionResendMessage" }, { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, { "$ref": "#/components/schemas/ActionStarMessage" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, { "$ref": "#/components/schemas/ActionSetMessageVar" }, { "$ref": "#/components/schemas/ActionRunSubroutine" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerMessageService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" } ] }, "VoiceAction": { "type": "object", "description": "An action available for `voice_actions` service type.", "discriminator": { "propertyName": "type", "mapping": { "play_audio": "#/components/schemas/ActionPlayAudio", "forward_call": "#/components/schemas/ActionForwardCall", "call_contact": "#/components/schemas/ActionCallContact", "hangup": "#/components/schemas/ActionHangup", "record_audio": "#/components/schemas/ActionRecordAudio", "wait_for_key": "#/components/schemas/ActionWaitForKey", "wait_for_digits": "#/components/schemas/ActionWaitForDigits", "reply": "#/components/schemas/ActionReply", "send_text": "#/components/schemas/ActionSendText", "send_text_to_group": "#/components/schemas/ActionSendTextToGroup", "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "set_contact": "#/components/schemas/ActionSetContact", "set_contact_name": "#/components/schemas/ActionSetContactName", "set_contact_var": "#/components/schemas/ActionSetContactVar", "block_contact": "#/components/schemas/ActionBlockContact", "send_email": "#/components/schemas/ActionSendEmail", "send_airtime": "#/components/schemas/ActionSendAirtime", "add_label_to_message": "#/components/schemas/ActionAddLabelToMessage", "star_message": "#/components/schemas/ActionStarMessage", "set_variable": "#/components/schemas/ActionSetVariable", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "run_script": "#/components/schemas/ActionRunScript", "condition": "#/components/schemas/ActionCondition", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_message_service": "#/components/schemas/ActionTriggerMessageService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService", "stop": "#/components/schemas/ActionStop", "copy_message_to_project": "#/components/schemas/ActionCopyMessageToProject", "set_message_var": "#/components/schemas/ActionSetMessageVar", "run_subroutine": "#/components/schemas/ActionRunSubroutine" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionPlayAudio" }, { "$ref": "#/components/schemas/ActionPlayAudio" }, { "$ref": "#/components/schemas/ActionForwardCall" }, { "$ref": "#/components/schemas/ActionCallContact" }, { "$ref": "#/components/schemas/ActionHangup" }, { "$ref": "#/components/schemas/ActionRecordAudio" }, { "$ref": "#/components/schemas/ActionWaitForKey" }, { "$ref": "#/components/schemas/ActionWaitForDigits" }, { "$ref": "#/components/schemas/ActionReply" }, { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendTextToGroup" }, { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionSetContact" }, { "$ref": "#/components/schemas/ActionSetContactName" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSendAirtime" }, { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, { "$ref": "#/components/schemas/ActionStarMessage" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerMessageService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, { "$ref": "#/components/schemas/ActionSetMessageVar" }, { "$ref": "#/components/schemas/ActionRunSubroutine" } ] }, "USSDAction": { "type": "object", "description": "An action available for `ussd_actions` service type.", "discriminator": { "propertyName": "type", "mapping": { "send_ussd_reply": "#/components/schemas/ActionSendUssdReply", "end_session": "#/components/schemas/ActionEndSession", "wait_ussd_response": "#/components/schemas/ActionWaitUssdResponse", "reply": "#/components/schemas/ActionReply", "send_text": "#/components/schemas/ActionSendText", "send_text_to_group": "#/components/schemas/ActionSendTextToGroup", "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "set_contact": "#/components/schemas/ActionSetContact", "set_contact_name": "#/components/schemas/ActionSetContactName", "set_contact_var": "#/components/schemas/ActionSetContactVar", "block_contact": "#/components/schemas/ActionBlockContact", "send_email": "#/components/schemas/ActionSendEmail", "send_airtime": "#/components/schemas/ActionSendAirtime", "add_label_to_message": "#/components/schemas/ActionAddLabelToMessage", "star_message": "#/components/schemas/ActionStarMessage", "set_variable": "#/components/schemas/ActionSetVariable", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "run_script": "#/components/schemas/ActionRunScript", "condition": "#/components/schemas/ActionCondition", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_message_service": "#/components/schemas/ActionTriggerMessageService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService", "stop": "#/components/schemas/ActionStop", "copy_message_to_project": "#/components/schemas/ActionCopyMessageToProject", "set_message_var": "#/components/schemas/ActionSetMessageVar", "run_subroutine": "#/components/schemas/ActionRunSubroutine" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionSendUssdReply" }, { "$ref": "#/components/schemas/ActionEndSession" }, { "$ref": "#/components/schemas/ActionWaitUssdResponse" }, { "$ref": "#/components/schemas/ActionReply" }, { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendTextToGroup" }, { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionSetContact" }, { "$ref": "#/components/schemas/ActionSetContactName" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSendAirtime" }, { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, { "$ref": "#/components/schemas/ActionStarMessage" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerMessageService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, { "$ref": "#/components/schemas/ActionSetMessageVar" }, { "$ref": "#/components/schemas/ActionRunSubroutine" } ] }, "ButtonPageAction": { "type": "object", "description": "An action available for `opt_out_page` and `button_page` service types.", "discriminator": { "propertyName": "type", "mapping": { "reply": "#/components/schemas/ActionReply", "send_text": "#/components/schemas/ActionSendText", "send_text_to_group": "#/components/schemas/ActionSendTextToGroup", "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "set_contact": "#/components/schemas/ActionSetContact", "set_contact_name": "#/components/schemas/ActionSetContactName", "set_contact_var": "#/components/schemas/ActionSetContactVar", "block_contact": "#/components/schemas/ActionBlockContact", "send_email": "#/components/schemas/ActionSendEmail", "send_airtime": "#/components/schemas/ActionSendAirtime", "add_label_to_message": "#/components/schemas/ActionAddLabelToMessage", "star_message": "#/components/schemas/ActionStarMessage", "set_variable": "#/components/schemas/ActionSetVariable", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "run_script": "#/components/schemas/ActionRunScript", "condition": "#/components/schemas/ActionCondition", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_message_service": "#/components/schemas/ActionTriggerMessageService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService", "stop": "#/components/schemas/ActionStop", "copy_message_to_project": "#/components/schemas/ActionCopyMessageToProject", "set_message_var": "#/components/schemas/ActionSetMessageVar", "run_subroutine": "#/components/schemas/ActionRunSubroutine" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionReply" }, { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendTextToGroup" }, { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionSetContact" }, { "$ref": "#/components/schemas/ActionSetContactName" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSendAirtime" }, { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, { "$ref": "#/components/schemas/ActionStarMessage" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerMessageService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, { "$ref": "#/components/schemas/ActionSetMessageVar" }, { "$ref": "#/components/schemas/ActionRunSubroutine" } ] }, "MessagingPollAction": { "type": "object", "description": "An action available for `messaging_poll` service type.", "discriminator": { "propertyName": "type", "mapping": { "skip_to_question": "#/components/schemas/ActionSkipToQuestion", "end_survey": "#/components/schemas/ActionEndSurvey", "repeat_question": "#/components/schemas/ActionRepeatQuestion", "ignore_message": "#/components/schemas/ActionIgnoreMessage", "reply_simple": "#/components/schemas/ActionReplySimple", "reply": "#/components/schemas/ActionReply", "send_text": "#/components/schemas/ActionSendText", "send_text_to_group": "#/components/schemas/ActionSendTextToGroup", "add_contact_to_group": "#/components/schemas/ActionAddContactToGroup", "remove_contact_from_group": "#/components/schemas/ActionRemoveContactFromGroup", "set_contact": "#/components/schemas/ActionSetContact", "set_contact_name": "#/components/schemas/ActionSetContactName", "set_contact_var": "#/components/schemas/ActionSetContactVar", "block_contact": "#/components/schemas/ActionBlockContact", "send_email": "#/components/schemas/ActionSendEmail", "send_airtime": "#/components/schemas/ActionSendAirtime", "add_label_to_message": "#/components/schemas/ActionAddLabelToMessage", "star_message": "#/components/schemas/ActionStarMessage", "set_variable": "#/components/schemas/ActionSetVariable", "cancel_scheduled_messages": "#/components/schemas/ActionCancelScheduledMessages", "webhook": "#/components/schemas/ActionWebhook", "log": "#/components/schemas/ActionLog", "run_script": "#/components/schemas/ActionRunScript", "condition": "#/components/schemas/ActionCondition", "trigger_contact_service": "#/components/schemas/ActionTriggerContactService", "trigger_message_service": "#/components/schemas/ActionTriggerMessageService", "trigger_project_service": "#/components/schemas/ActionTriggerProjectService", "stop": "#/components/schemas/ActionStop", "copy_message_to_project": "#/components/schemas/ActionCopyMessageToProject", "set_message_var": "#/components/schemas/ActionSetMessageVar" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionSkipToQuestion" }, { "$ref": "#/components/schemas/ActionEndSurvey" }, { "$ref": "#/components/schemas/ActionRepeatQuestion" }, { "$ref": "#/components/schemas/ActionIgnoreMessage" }, { "$ref": "#/components/schemas/ActionReplySimple" }, { "$ref": "#/components/schemas/ActionReply" }, { "$ref": "#/components/schemas/ActionSendText" }, { "$ref": "#/components/schemas/ActionSendTextToGroup" }, { "$ref": "#/components/schemas/ActionAddContactToGroup" }, { "$ref": "#/components/schemas/ActionRemoveContactFromGroup" }, { "$ref": "#/components/schemas/ActionSetContact" }, { "$ref": "#/components/schemas/ActionSetContactName" }, { "$ref": "#/components/schemas/ActionSetContactVar" }, { "$ref": "#/components/schemas/ActionBlockContact" }, { "$ref": "#/components/schemas/ActionSendEmail" }, { "$ref": "#/components/schemas/ActionSendAirtime" }, { "$ref": "#/components/schemas/ActionAddLabelToMessage" }, { "$ref": "#/components/schemas/ActionStarMessage" }, { "$ref": "#/components/schemas/ActionSetVariable" }, { "$ref": "#/components/schemas/ActionCancelScheduledMessages" }, { "$ref": "#/components/schemas/ActionWebhook" }, { "$ref": "#/components/schemas/ActionLog" }, { "$ref": "#/components/schemas/ActionRunScript" }, { "$ref": "#/components/schemas/ActionCondition" }, { "$ref": "#/components/schemas/ActionTriggerContactService" }, { "$ref": "#/components/schemas/ActionTriggerMessageService" }, { "$ref": "#/components/schemas/ActionTriggerProjectService" }, { "$ref": "#/components/schemas/ActionStop" }, { "$ref": "#/components/schemas/ActionCopyMessageToProject" }, { "$ref": "#/components/schemas/ActionSetMessageVar" } ] }, "RoutingAction": { "type": "object", "description": "A routing action for custom routes. Only `use_phone` and `condition` action types are supported.", "discriminator": { "propertyName": "type", "mapping": { "use_phone": "#/components/schemas/ActionUsePhone", "condition": "#/components/schemas/ActionCondition" } }, "oneOf": [ { "$ref": "#/components/schemas/ActionUsePhone" }, { "$ref": "#/components/schemas/ActionCondition" } ] }, "Message": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the message", "example": "SM1629708e59c5c781" }, "direction": { "type": "string", "description": "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", "enum": [ "incoming", "outgoing" ], "example": "outgoing" }, "status": { "type": "string", "description": "Current status of the message", "enum": [ "ignored", "processing", "received", "sent", "queued", "failed", "failed_queued", "cancelled", "delivered", "not_delivered", "read" ], "example": "sent" }, "message_type": { "type": "string", "description": "Type of the message", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ], "example": "sms" }, "source": { "type": "string", "description": "How the message originated within Telerivet", "enum": [ "phone", "provider", "web", "api", "service", "webhook", "scheduled", "integration", "mcp" ], "example": "service" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "The time that the message was created on Telerivet's servers", "example": 1390347812 }, "time_sent": { "type": "integer", "format": "unix-timestamp", "description": "The time that the message was reported to have been sent (null for incoming messages and messages that have not yet been sent)", "example": 1390347814, "nullable": true }, "time_updated": { "type": "integer", "format": "unix-timestamp", "description": "The time that the message was last updated in Telerivet.", "example": 1390347818 }, "from_number": { "type": "string", "description": "The phone number that the message originated from (your number for outgoing messages, the contact's number for incoming messages)", "example": "+16505550001" }, "to_number": { "type": "string", "description": "The phone number that the message was sent to (your number for incoming messages, the contact's number for outgoing messages)", "example": "+16505550123" }, "content": { "type": "string", "description": "The text content of the message (null for USSD messages and calls)", "example": "Thank you for registering!" }, "starred": { "type": "boolean", "description": "Whether this message is starred in Telerivet", "example": true }, "simulated": { "type": "boolean", "description": "Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone)", "example": false }, "label_ids": { "type": "string", "description": "List of IDs of labels applied to this message" }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message. \n\n 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.\n\n For more details, see Route-Specific Parameters.", "nullable": true }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "priority": { "type": "integer", "description": "Priority of this message. Telerivet will attempt to send messages with higher priority numbers first. Only defined for outgoing messages.", "example": 1 }, "send_attempts": { "type": "number", "description": "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.", "example": 1, "nullable": true }, "error_message": { "type": "string", "description": "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_code": { "type": "string", "description": "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.)" }, "external_id": { "type": "string", "description": "The ID of this message from an external SMS gateway provider (e.g. Twilio or Vonage), if available.", "example": "142092393" }, "num_parts": { "type": "number", "description": "The number of SMS parts associated with the message, if applicable and if known.", "example": 1, "nullable": true }, "price": { "type": "number", "description": "The price of this message, if known.", "example": 0.01, "nullable": true }, "price_currency": { "type": "string", "description": "The currency of the message price, if applicable.", "example": "USD" }, "duration": { "type": "number", "description": "The duration of the call in seconds, if known, or -1 if the call was not answered.", "nullable": true }, "ring_time": { "type": "number", "description": "The length of time the call rang in seconds before being answered or hung up, if known.", "nullable": true }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call" }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice", "enum": [ "female", "male" ] }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content are short URLs that redirect to a destination URL." }, "short_urls": { "type": "array", "items": { "type": "object", "properties": { "short_url": { "type": "string", "description": "The short URL" }, "link_type": { "type": "string", "description": "Type of link: redirect, media, or service" }, "time_clicked": { "type": "integer", "format": "unix-timestamp", "description": "First time this URL was clicked" }, "expiration_time": { "type": "integer", "format": "unix-timestamp", "description": "When this short URL expires" }, "destination_url": { "type": "string", "description": "Destination URL (when link_type is redirect)" }, "media_index": { "type": "integer", "description": "Index in media array (when link_type is media)" }, "service_id": { "type": "string", "description": "Service ID (when link_type is service)" } } }, "description": "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." }, "network_code": { "type": "string", "description": "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](https://en.wikipedia.org/wiki/Mobile_country_code). The network_code property may be non-numeric for messages not sent via mobile networks." }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments for the text message. This property is undefined for messages that do not contain media files." }, "mms_parts": { "type": "array", "items": { "type": "object", "properties": { "cid": { "type": "string", "description": "MMS content-id" }, "type": { "type": "string", "description": "MIME type" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "Number of bytes" }, "url": { "type": "string", "description": "URL where the content is stored" } } }, "description": "A list of parts in the MMS message (only for incoming MMS messages received via Telerivet Gateway Android app).\n\n Each MMS part in the list is an object with the following properties:\n\n - cid: MMS content-id\n - type: MIME type\n - filename: original filename\n - size (int): number of bytes\n - 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)\n\n In general, the `media` property of the message is recommended for retrieving information about MMS media files, instead of `mms_parts`.\n The `mms_parts` property is also only present when retrieving an individual MMS message by ID, not when querying a list of messages." }, "time_clicked": { "type": "integer", "format": "unix-timestamp", "description": "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." }, "service_id": { "type": "string", "description": "ID of the service that handled the message (for voice calls, the service defines the call flow)", "example": "SV3d246818d0e3d1fb" }, "phone_id": { "type": "string", "description": "ID of the phone (basic route) that sent or received the message", "example": "PN4d246818d0ecd1fa" }, "contact_id": { "type": "string", "description": "ID of the contact that sent or received the message", "example": "CTa1299c3d0e371023" }, "route_id": { "type": "string", "description": "ID of the custom route that sent the message (if applicable)", "example": "RT2a586298d3412adf" }, "broadcast_id": { "type": "string", "description": "ID of the broadcast that this message is part of (if applicable)", "example": "MB98918598dab29800" }, "scheduled_id": { "type": "string", "description": "ID of the scheduled message that created this message is part of (if applicable)", "example": "SEa502e6f9d23f1cb6" }, "user_id": { "type": "string", "description": "ID of the Telerivet user who sent the message (if applicable)", "example": "URba3e403e98f49735" }, "project_id": { "type": "string", "description": "ID of the project this contact belongs to", "example": "PJ2ad0100821a98bea" }, "url": { "type": "string", "description": "URL to the message detail page in the Telerivet web app", "example": "https://telerivet.com/p/asdf/message/SM1629708e59c5c781" } }, "description": "Represents a single message." }, "ScheduledMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the scheduled message", "example": "SEfaf2411ed3584f08" }, "content": { "type": "string", "description": "Text content of the scheduled message", "example": "hello world!" }, "rrule": { "type": "string", "description": "Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see [RFC2445](https://tools.ietf.org/html/rfc2445#section-4.3.10).", "example": "COUNT=1" }, "timezone_id": { "type": "string", "description": "Timezone ID used to compute times for recurring messages; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "List of recipients. Each recipient is an object with a string `type` property, which may be `\"phone_number\"`, `\"group\"`, or `\"filter\"`.\n\n If the type is `\"phone_number\"`, the `phone_number` property will be set to the recipient's phone number.\n\n 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.\n\n 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.)" }, "recipients_str": { "type": "string", "description": "A string with a human readable description of the first few recipients (possibly truncated)", "example": "+16505550123, Subscribers" }, "group_id": { "type": "string", "description": "ID of the group to send the message to (null if the recipient is an individual contact, or if there are multiple recipients)" }, "contact_id": { "type": "string", "description": "ID of the contact to send the message to (null if the recipient is a group, or if there are multiple recipients)" }, "to_number": { "type": "string", "description": "Phone number to send the message to (null if the recipient is a group, or if there are multiple recipients)" }, "route_id": { "type": "string", "description": "ID of the phone or route the message will be sent from", "example": "PN4d246818d0ecd1fa" }, "service_id": { "type": "string", "description": "The service associated with this message (for voice calls, the service defines the call flow)", "example": "SV3d246818d0e3d1fb" }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call" }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice", "enum": [ "female", "male" ] }, "message_type": { "type": "string", "description": "Type of scheduled message", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ], "example": "sms" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the scheduled message was created in Telerivet", "example": 1395617416 }, "start_time": { "type": "integer", "format": "unix-timestamp", "description": "The time that the message will be sent (or first sent for recurring messages)", "example": 1395617516 }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which a recurring message will stop (not applicable to non-recurring scheduled messages)", "nullable": true }, "prev_time": { "type": "integer", "format": "unix-timestamp", "description": "The most recent time that Telerivet has sent this scheduled message (null if it has never been sent)", "nullable": true }, "next_time": { "type": "integer", "format": "unix-timestamp", "description": "The next upcoming time that Telerivet will sent this scheduled message (null if it will not be sent again)", "example": 1395617516, "nullable": true }, "occurrences": { "type": "integer", "description": "Number of times this scheduled message has already been sent", "example": 0 }, "replace_variables": { "type": "boolean", "description": "Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise", "example": false }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments for the text message. This property is undefined for messages that do not contain media files." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending the message. \n\n 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.\n\n For more details, see Route-Specific Parameters.", "nullable": true }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "label_ids": { "type": "string", "description": "IDs of labels to add to the Message" }, "relative_scheduled_id": { "type": "string", "description": "ID of the relative scheduled message this scheduled message was created from, if applicable", "example": "PJ2ad0100821a98bea" }, "project_id": { "type": "string", "description": "ID of the project this scheduled message belongs to", "example": "PJ2ad0100821a98bea" }, "is_template": { "type": "boolean", "description": "Set to true if Telerivet will render variables like [[contact.name]] in the message content" } }, "description": "Represents a scheduled message within Telerivet." }, "RelativeScheduledMessage": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the relative scheduled message", "example": "SEfaf2411ed3584f08" }, "content": { "type": "string", "description": "Text content of the relative scheduled message", "example": "hello world!" }, "time_of_day": { "type": "string", "description": "Time of day when scheduled messages will be sent in HH:MM format (with hours from 00 to 23)", "example": "15:07" }, "date_variable": { "type": "string", "description": "Custom contact variable storing date or date/time values relative to which messages will be scheduled.", "example": "date" }, "offset_scale": { "type": "string", "description": "The type of interval 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 (I=minutes, D=day, W=week, M=month, Y=year)", "enum": [ "I", "D", "W", "M", "Y" ], "example": "D" }, "offset_count": { "type": "integer", "description": "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.", "example": 3 }, "rrule": { "type": "string", "description": "Recurrence rule for recurring scheduled messages, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see [RFC2445](https://tools.ietf.org/html/rfc2445#section-4.3.10).", "example": "COUNT=1" }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which recurring messages will stop (not applicable to non-recurring scheduled messages)", "nullable": true }, "timezone_id": { "type": "string", "description": "Timezone ID used to compute times for recurring messages; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "recipients_str": { "type": "string", "description": "A string with a human readable description of the recipient", "example": "Subscribers" }, "group_id": { "type": "string", "description": "ID of the group to send the message to (null if the recipient is an individual contact)" }, "contact_id": { "type": "string", "description": "ID of the contact to send the message to (null if the recipient is a group)" }, "to_number": { "type": "string", "description": "Phone number to send the message to (null if the recipient is a group)" }, "route_id": { "type": "string", "description": "ID of the phone or route the message will be sent from", "example": "PN4d246818d0ecd1fa" }, "service_id": { "type": "string", "description": "The service associated with this message (for voice calls, the service defines the call flow)", "example": "SV3d246818d0e3d1fb" }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call" }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice", "enum": [ "female", "male" ] }, "message_type": { "type": "string", "description": "Type of scheduled message", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ], "example": "sms" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the relative scheduled message was created in Telerivet", "example": 1395617416 }, "replace_variables": { "type": "boolean", "description": "Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise", "example": false }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments for the text message. This property is undefined for messages that do not contain media files." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending the message. \n\n 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.\n\n For more details, see Route-Specific Parameters.", "nullable": true }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "label_ids": { "type": "string", "description": "IDs of labels to add to the Message" }, "project_id": { "type": "string", "description": "ID of the project this relative scheduled message belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "A relative scheduled message is a message that is scheduled relative to a date stored as a custom field for each recipient contact.\n 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.\n\n Telerivet will automatically create a ScheduledMessage for each contact matching a RelativeScheduledMessage.\n\n 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." }, "ScheduledService": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the scheduled service", "example": "SEfaf2411ed3584f08" }, "service_id": { "type": "string", "description": "ID of the service to be triggered", "example": "SVa1299c3d0e371023" }, "rrule": { "type": "string", "description": "Recurrence rule for recurring scheduled services, e.g. 'FREQ=MONTHLY' or 'FREQ=WEEKLY;INTERVAL=2'; see [RFC2445](https://tools.ietf.org/html/rfc2445#section-4.3.10).", "example": "COUNT=1" }, "timezone_id": { "type": "string", "description": "Timezone ID used to compute times for recurring scheduled services; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the scheduled service was created in Telerivet", "example": 1395617416 }, "start_time": { "type": "integer", "format": "unix-timestamp", "description": "The time that the service will be triggered (or first triggered for recurring scheduled services)", "example": 1395617516 }, "end_time": { "type": "integer", "format": "unix-timestamp", "description": "Time after which a recurring scheduled service will stop (not applicable to non-recurring scheduled services)", "nullable": true }, "prev_time": { "type": "integer", "format": "unix-timestamp", "description": "The most recent time that Telerivet triggered this scheduled service (null if it has never been triggered)", "nullable": true }, "next_time": { "type": "integer", "format": "unix-timestamp", "description": "The next upcoming time that Telerivet will trigger this scheduled service (null if it will not be triggered again)", "example": 1395617516, "nullable": true }, "occurrences": { "type": "integer", "description": "Number of times this scheduled service has already been triggered", "example": 0 }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this scheduled service. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "project_id": { "type": "string", "description": "ID of the project this scheduled service belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents a scheduled service within Telerivet.\n\n Scheduled services allow services to be triggered automatically at specified times.\n The ScheduledService object is only used for services that are triggered for a project (e.g. `scheduled_actions` or `scheduled_script`).\n\n Note: To schedule services that are triggered for a contact, the ScheduledMessage object should be used instead, with `message_type`=`service`." }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the contact", "example": "CTa1299c3d0e371023" }, "name": { "type": "string", "description": "Name of the contact", "example": "John Smith" }, "phone_number": { "type": "string", "description": "Phone number of the contact", "example": "+16505550123" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the contact was added in Telerivet", "example": 1390348075 }, "time_updated": { "type": "integer", "format": "unix-timestamp", "description": "Time the contact was last updated in Telerivet", "example": 1390348099 }, "send_blocked": { "type": "boolean", "description": "True if Telerivet is blocked from sending messages to this contact", "example": false }, "conversation_status": { "type": "string", "description": "Current status of the conversation with this contact", "enum": [ "closed", "active", "handled" ], "example": "active" }, "last_message_time": { "type": "integer", "format": "unix-timestamp", "description": "Last time the contact sent or received a message (null if no messages have been sent or received)", "example": 1395881121, "nullable": true }, "last_incoming_message_time": { "type": "integer", "format": "unix-timestamp", "description": "Last time a message was received from this contact", "example": 1395881121, "nullable": true }, "last_outgoing_message_time": { "type": "integer", "format": "unix-timestamp", "description": "Last time a message was sent to this contact", "example": 1395881032, "nullable": true }, "message_count": { "type": "integer", "description": "Total number of non-deleted messages sent to or received from this contact", "example": 13 }, "incoming_message_count": { "type": "integer", "description": "Number of messages received from this contact", "example": 2 }, "outgoing_message_count": { "type": "integer", "description": "Number of messages sent to this contact", "example": 11 }, "last_message_id": { "type": "string", "description": "ID of the last message sent to or received from this contact (null if no messages have been sent or received)", "example": "SM97f47ac232df154d" }, "default_route_id": { "type": "string", "description": "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)" }, "group_ids": { "type": "array", "items": { "type": "string" }, "description": "List of IDs of groups that this contact belongs to" }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "project_id": { "type": "string", "description": "ID of the project this contact belongs to", "example": "PJ2ad0100821a98bea" }, "url": { "type": "string", "description": "URL to this contact in the Telerivet web app", "example": "https://telerivet.com/p/asdf/contact/CTa1299c3d0e371023" } }, "description": "A contact represents a person or other entity that can be communicated with via phone number or other messaging channel within a project.\n\n Each contact has a name, phone number, and custom variables that can be used to personalize messages. Contacts can belong to one or more groups, and can be used as recipients for broadcasts, campaigns, and other messaging operations.\n\n Contacts can be imported or created individually via the API or web app. If the project's auto_create_contacts setting is enabled, a contact will be automatically created for each unique phone number that a message is sent to or received from." }, "Broadcast": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the broadcast", "example": "MB2489812e59c5c781" }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "List of recipients. Each recipient is an object with a string `type` property, which may be `\"phone_number\"`, `\"group\"`, or `\"filter\"`.\n\n If the type is `\"phone_number\"`, the `phone_number` property will be set to the recipient's phone number.\n\n 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.\n\n 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.)" }, "title": { "type": "string", "description": "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)", "example": "+16505550123, Subscribers, Contact Filter" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the broadcast was sent in Telerivet", "example": 1390348075 }, "last_message_time": { "type": "integer", "format": "unix-timestamp", "description": "Time the most recent message was queued to send in this broadcast", "example": 1390348085, "nullable": true }, "last_send_time": { "type": "integer", "format": "unix-timestamp", "description": "Time the most recent message was sent (or failed to send) in this broadcast, or null if no messages have been sent yet", "example": 1390348086, "nullable": true }, "status_counts": { "type": "object", "additionalProperties": true, "description": "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." }, "message_count": { "type": "integer", "description": "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.", "example": 8358 }, "estimated_count": { "type": "integer", "description": "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.", "example": 12942 }, "num_parts": { "type": "number", "description": "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.", "example": 12321, "nullable": true }, "message_type": { "type": "string", "description": "Type of message sent from this broadcast", "enum": [ "sms", "mms", "ussd", "ussd_session", "call", "chat", "service" ], "example": "sms" }, "content": { "type": "string", "description": "The text content of the message (null for USSD messages and calls)", "example": "Hello [[contact.name]]!" }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call" }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice", "enum": [ "female", "male" ] }, "replace_variables": { "type": "boolean", "description": "Set to true if Telerivet will render variables like [[contact.name]] in the message content, false otherwise", "example": true }, "status": { "type": "string", "description": "The current status of the broadcast.", "enum": [ "queuing", "sending", "complete", "cancelled" ], "example": "queuing" }, "source": { "type": "string", "description": "How the message originated within Telerivet", "enum": [ "phone", "provider", "web", "api", "service", "webhook", "scheduled", "integration", "mcp" ], "example": "service" }, "simulated": { "type": "boolean", "description": "Whether this message was simulated within Telerivet for testing (and not actually sent to or received by a real phone)", "example": false }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the message content will automatically be replaced with unique short URLs." }, "clicked_count": { "type": "integer", "description": "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.", "example": 12, "nullable": true }, "label_ids": { "type": "string", "description": "List of IDs of labels applied to all messages in the broadcast" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments for the text message. This property is undefined for messages that do not contain media files." }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the messages in the broadcast. \n\n 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.\n\n For more details, see Route-Specific Parameters.", "nullable": true }, "price": { "type": "number", "description": "The total price of all messages in this broadcast, if known.", "example": 13.34, "nullable": true }, "price_currency": { "type": "string", "description": "The currency of the message price, if applicable.", "example": "USD" }, "reply_count": { "type": "integer", "description": "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`.)", "example": 43 }, "last_reply_time": { "type": "integer", "format": "unix-timestamp", "description": "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", "example": 1390348132, "nullable": true }, "route_id": { "type": "string", "description": "ID of the phone or route used to send the broadcast (if applicable)", "example": "RT2a586298d3412adf" }, "service_id": { "type": "string", "description": "The service associated with this broadcast (for voice calls, the service defines the call flow)", "example": "SV3d246818d0e3d1fb" }, "url": { "type": "string", "description": "URL to this broadcast in the Telerivet web app", "example": "https://telerivet.com/p/asdf/broadcast/MB2489812e59c5c781", "nullable": true }, "user_id": { "type": "string", "description": "ID of the Telerivet user who sent the broadcast (if applicable)", "example": "URba3e403e98f49735" }, "project_id": { "type": "string", "description": "ID of the project this broadcast belongs to", "example": "PJ2ad0100821a98bea" }, "is_template": { "type": "boolean", "description": "Set to true if Telerivet will render variables like [[contact.name]] in the message content" }, "recipients_str": { "type": "string", "description": "A string with a human readable description of the first few recipients (possibly truncated)" } }, "description": "Represents a collection of related outgoing messages.\n 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.\n A broadcast is automatically created when sending a message to a group of contacts." }, "Campaign": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the campaign", "example": "CM2ad0100821a98bea" }, "name": { "type": "string", "description": "Name of the campaign, which must be unique within the project. The campaign name is only visible within Telerivet, and does not appear in the messages sent to contacts.", "example": "Test Campaign" }, "campaign_type": { "type": "string", "description": "Type of the campaign. The following campaign types are available:\n\n - `broadcast_text` - Send a text message to a group of contacts\n - `broadcast_call` - Send a voice call to a group of contacts\n - `broadcast_svc` - Trigger a service for a group of contacts\n - `relative` - Send a series of messages over time relative to when each contact was added to a group\n - `anniversary` - Send messages on recurring dates (e.g. birthdays, anniversaries)", "enum": [ "broadcast_text", "broadcast_call", "broadcast_svc", "relative", "anniversary" ], "example": "broadcast_text" }, "status": { "type": "string", "description": "Current status of the campaign", "enum": [ "draft", "scheduled", "sent", "pending_review" ], "example": "draft" }, "group_id": { "type": "string", "description": "ID of the group of contacts that the campaign will be sent to", "example": "CG02139128391fa" }, "exclude_group_id": { "type": "string", "description": "ID of a group of contacts to exclude from the campaign", "nullable": true }, "route_id": { "type": "string", "description": "ID of the phone or route used to send the campaign", "example": "RT2a586298d3412adf" }, "broadcast_id": { "type": "string", "description": "ID of the most recent broadcast created by this campaign, if applicable", "example": "MB2489812e59c5c781", "nullable": true }, "estimated_count": { "type": "integer", "description": "Estimated number of messages that will be sent in this campaign", "example": 12942, "nullable": true }, "message_count": { "type": "integer", "description": "Number of messages that have been sent in this campaign", "example": 8358, "nullable": true }, "respondent_group_id": { "type": "string", "description": "ID of a group to add contacts to after they respond to the campaign", "nullable": true }, "clicked_group_id": { "type": "string", "description": "ID of a group to add contacts to after they click a link in the campaign", "nullable": true }, "label_ids": { "type": "string", "description": "List of IDs of labels applied to messages sent by this campaign" }, "schedule_mode": { "type": "string", "description": "Indicates whether the campaign should be sent immediately or at a future time (applies to broadcast campaign types). If `schedule_time` is set, `schedule_mode` is automatically set to `at_time`. If `schedule_mode` is set to `immediate` or `null`, `schedule_time` is automatically cleared.\n\n Note that after setting schedule_mode to \"immediate\" on a campaign with the `draft` status, the campaign will not actually be sent until the API method is called to send the campaign.", "enum": [ "immediate", "at_time" ], "example": "immediate", "nullable": true }, "schedule_time": { "type": "integer", "format": "unix-timestamp", "description": "The time to send the campaign, as a UNIX timestamp (applies to broadcast campaign types). Setting this to a non-null value automatically sets `schedule_mode` to `at_time`.\n\n Note that after setting schedule_time on a campaign with the `draft` status, the campaign will not actually be scheduled until the API method is called to schedule the campaign.", "nullable": true }, "content": { "type": "string", "description": "Text content of the message (applies to `broadcast_text` campaigns), or the text-to-speech text for voice calls (applies to `broadcast_call` campaigns). May contain variables like `[[contact.name]]`.\n\n (See available variables)", "example": "Hello world", "nullable": true }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments (applies to `broadcast_text` campaigns).", "nullable": true }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message (applies to `broadcast_text` campaigns). See Route-Specific Parameters.", "nullable": true }, "track_clicks": { "type": "boolean", "description": "Whether to shorten links and track link clicks (applies to `broadcast_text` campaigns)." }, "short_link_params": { "type": "object", "properties": { "domain": { "type": "string", "description": "Custom domain for short links. Must be configured for this project." }, "expiration_sec": { "type": "integer", "description": "Expiration time in seconds for short links." } }, "description": "Parameters for short links when `track_clicks` is enabled (applies to `broadcast_text` campaigns).", "nullable": true }, "audio_url": { "type": "string", "description": "For voice calls, the URL of an MP3 file to play when the contact answers the call (applies to `broadcast_call` campaigns)", "nullable": true }, "tts_lang": { "type": "string", "description": "For voice calls, the language of the text-to-speech voice (applies to `broadcast_call` campaigns)", "enum": [ "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": { "type": "string", "description": "For voice calls, the text-to-speech voice (applies to `broadcast_call` campaigns)", "enum": [ "female", "male" ] }, "service_id": { "type": "string", "description": "ID of the service associated with this campaign (applies to `broadcast_call` or `broadcast_svc` campaigns)", "example": "SV3d246818d0e3d1fb", "nullable": true }, "date_variable": { "type": "string", "description": "Custom contact variable storing date or date/time values relative to which messages will be scheduled (applies to `relative` and `anniversary` campaigns)", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "mode": { "type": "string", "description": "Type of message to send: `\"text\"`, `\"service\"`, or `\"call\"`" }, "offset_count": { "type": "integer", "description": "The number of days/weeks/months/years to adjust the date of the scheduled message relative to the date stored in the contact variable. May be positive (after), negative (before), or zero (on the date)." }, "offset_scale": { "type": "string", "description": "The type of interval for the offset (I=minutes, D=day, W=week, M=month, Y=year)." }, "time_of_day": { "type": "string", "description": "Time of day when messages will be sent, in HH:MM format (with hours from 00 to 23)." }, "content": { "type": "string", "description": "Text content of the message (when `mode` is `\"text\"`), or the text-to-speech text for voice calls (when `mode` is `\"call\"`). May contain variables like `[[contact.name]]`.\n\n [(See available variables)](#variables)" }, "media": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day." }, "type": { "type": "string", "description": "MIME type of the media file" }, "filename": { "type": "string", "description": "Original filename" }, "size": { "type": "integer", "description": "File size in bytes" }, "file_id": { "type": "string", "description": "ID of the stored file, if applicable" } } }, "description": "Array of media attachments (when `mode` is `\"text\"`)." }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters for the message (when `mode` is `\"text\"`). See [Route-Specific Parameters](#route_params)." }, "track_clicks": { "type": "boolean", "description": "Whether to shorten links and track link clicks (when `mode` is `\"text\"`)." }, "short_link_params": { "type": "object", "properties": { "domain": { "type": "string", "description": "Custom domain for short links. Must be configured for this project." }, "expiration_sec": { "type": "integer", "description": "Expiration time in seconds for short links." } }, "description": "Parameters for short links when `track_clicks` is enabled (when `mode` is `\"text\"`)." }, "service_id": { "type": "string", "description": "ID of the service to trigger (when `mode` is `\"service\"` or `\"call\"`)" }, "audio_url": { "type": "string", "description": "URL of an MP3 file to play for voice calls (when `mode` is `\"call\"`)" }, "tts_lang": { "type": "string", "description": "Language for text-to-speech voice calls (when `mode` is `\"call\"`)" }, "tts_voice": { "type": "string", "description": "Voice for text-to-speech voice calls (when `mode` is `\"call\"`)" } } }, "description": "Array of campaign items (applies to `relative` and `anniversary` campaigns). Each item defines a scheduled message with timing and content.", "nullable": true }, "message_type": { "type": "string", "description": "Type of messages sent by this campaign, or null if not applicable", "example": "sms", "nullable": true }, "timezone_id": { "type": "string", "description": "The ID of the timezone used for scheduling messages in this campaign, or null to use the project's default timezone", "example": "America/Los_Angeles", "nullable": true }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the campaign was created in Telerivet", "example": 1390348075 }, "time_updated": { "type": "integer", "format": "unix-timestamp", "description": "Time the campaign was last updated in Telerivet", "example": 1390348075 }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this campaign. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "url": { "type": "string", "description": "URL to view the campaign in the Telerivet web app", "example": "https://telerivet.com/p/asdf/campaign/CM2ad0100821a98bea" }, "url_edit": { "type": "string", "description": "URL to edit the campaign in the Telerivet web app", "example": "https://telerivet.com/p/asdf/campaign/CM2ad0100821a98bea/edit" }, "url_send": { "type": "string", "description": "URL to preview and send the campaign in the Telerivet web app", "example": "https://telerivet.com/p/asdf/campaign/CM2ad0100821a98bea/preview" }, "user_id": { "type": "string", "description": "ID of the Telerivet user who created the campaign", "example": "URba3e403e98f49735" }, "project_id": { "type": "string", "description": "ID of the project this campaign belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "A campaign is something that is sent to a group of contacts on a particular schedule.\n\n Depending on the campaign type, a campaign may send a text message, make a voice call, or trigger an automated service. A campaign may either send a single broadcast at once, or send multiple broadcasts to different contacts over time.\n\n Campaigns are initially created as a draft and can be edited and previewed before being sent. This supports a workflow where campaigns can be drafted via the API, and subsequently edited, approved, and sent via either the web app or the API. Once sent, a campaign creates one or more broadcasts to deliver messages to the target recipients.\n\n Campaigns build on top of other core entity types including broadcasts and scheduled messages. Although it is possible to send broadcasts or schedule messages directly via the API, campaigns can be used in order to provide the ability to save drafts, allow manual editing and approval before sending, or to organize broadcasts within Telerivet." }, "Task": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the task", "example": "DE1189812e59c5c781" }, "task_type": { "type": "string", "description": "The task type", "example": "add_group_members" }, "task_params": { "type": "object", "additionalProperties": true, "description": "Parameters applied to all matching rows (specific to `task_type`). See project.createTask." }, "filter_type": { "type": "string", "description": "Type of filter defining the rows that the task is applied to", "example": "query_contacts" }, "filter_params": { "type": "object", "additionalProperties": true, "description": "Parameters defining the rows that the task is applied to (specific to `filter_type`). See project.createTask." }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the task was created in Telerivet", "example": 1390348075 }, "time_active": { "type": "integer", "format": "unix-timestamp", "description": "Time Telerivet started executing the task", "example": 1390348076, "nullable": true }, "time_complete": { "type": "integer", "format": "unix-timestamp", "description": "Time Telerivet finished executing the task", "nullable": true }, "total_rows": { "type": "integer", "description": "The total number of rows matching the filter (null if not known)", "example": 12000, "nullable": true }, "current_row": { "type": "integer", "description": "The number of rows that have been processed so far", "example": 3000, "nullable": true }, "status": { "type": "string", "description": "The current status of the task", "enum": [ "created", "queued", "active", "complete", "failed", "cancelled" ], "example": "active" }, "error_message": { "type": "string", "description": "Error message if the task failed", "nullable": true }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "table_id": { "type": "string", "description": "ID of the data table this task is applied to (if applicable)" }, "user_id": { "type": "string", "description": "ID of the Telerivet user who created the task (if applicable)", "example": "URba3e403e98f49735" }, "project_id": { "type": "string", "description": "ID of the project this task belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents an asynchronous task that is applied to all entities matching a filter.\n\n 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;\n updating a custom variable; deleting contacts, messages, or data rows; or exporting data to CSV." }, "Project": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the project", "example": "PJ2ad0100821a98bea" }, "name": { "type": "string", "description": "Name of the project", "example": "Example Project" }, "timezone_id": { "type": "string", "description": "Default TZ database timezone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" }, "url_slug": { "type": "string", "description": "Unique string used as a component of the project's URL in the Telerivet web app (required length: 3-18 characters)", "example": "asdf" }, "default_route_id": { "type": "string", "description": "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." }, "auto_create_contacts": { "type": "boolean", "description": "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.", "example": true }, "message_retention_days": { "type": "integer", "description": "Number of days to retain messages in this project. Messages older than this will be automatically deleted. If null, messages will be retained forever.", "example": 90 }, "short_link_scheme": { "type": "boolean", "description": "If true (the default), short links in messages will include the scheme (e.g., 'https://rvt.me/xxxxxxxxx'). If false, short links will not include the scheme (e.g., 'rvt.me/xxxxxxxxx').", "example": true }, "vars": { "type": "object", "additionalProperties": true, "description": "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 _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "organization_id": { "type": "string", "description": "ID of the organization this project belongs to", "example": "AC1230123421123123" }, "url": { "type": "string", "description": "URL to this project in the Telerivet web app", "example": "https://telerivet.com/p/asdf" } }, "description": "Represents a Telerivet project.\n\n 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." }, "Label": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the label", "example": "LB4f3dac27154653e0" }, "name": { "type": "string", "description": "Name of the label", "example": "Important" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the label was created in Telerivet", "example": 1392254503 }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this label. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "project_id": { "type": "string", "description": "ID of the project this label belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents a label used to organize messages within Telerivet." }, "Group": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the group", "example": "CGb0b7201b222fa609" }, "name": { "type": "string", "description": "Name of the group", "example": "Subscribers" }, "dynamic": { "type": "boolean", "description": "Whether this is a dynamic or normal group", "example": false }, "filters": { "type": "object", "additionalProperties": true, "description": "Key-value pairs of conditions that contacts must match to be members of a dynamic group. To filter by a custom variable, precede the variable name with 'vars.' (conditions on custom variables may also be provided as a nested object under a `vars` key, e.g. `{\"vars\": {\"city\": \"Manila\"}}`); other supported keys are `id`, `name`, `phone_number`, `time_created`, `time_updated`, `incoming_message_count`, `outgoing_message_count`, `last_incoming_message_time`, `last_outgoing_message_time`, `conversation_status`, `send_blocked`, `group` (ID of a normal group whose members should be included), `not_group` (ID of a normal group whose members should be excluded), and `q` (full-text search query matching contacts like the search box in the web app). Each value is either a value to match exactly, or an object with an operator such as `ne`, `prefix`, `gte`, `lt`, `exists`, or `not_exists` as the key (e.g. `{\"gte\": 10}`). Null if this is a normal group. Filter conditions can only be updated on dynamic groups.", "nullable": true }, "num_members": { "type": "integer", "description": "Number of contacts in the group (null if the group is dynamic)", "example": 142, "nullable": true }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the group was created in Telerivet", "example": 1390343845 }, "allow_sending": { "type": "boolean", "description": "True if messages can be sent to this group, false otherwise." }, "add_time_variable": { "type": "string", "description": "Variable name of a custom contact field that will automatically be set to the current date/time on any contact that is added to the group. This variable will only be set if the contact does not already have a value for this variable.", "example": "subscription_time", "nullable": true }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this group. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "url": { "type": "string", "description": "URL to this group in the Telerivet web app", "example": "https://telerivet.com/p/asdf/group/CGb0b7201b222fa609" }, "project_id": { "type": "string", "description": "ID of the project this group belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents a group used to organize contacts within Telerivet." }, "Phone": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the phone", "example": "PN4d246818d0ecd1fa" }, "name": { "type": "string", "description": "Name of the phone", "example": "Android Phone 1" }, "phone_number": { "type": "string", "description": "Phone number or sender ID", "example": "+16505550001" }, "phone_type": { "type": "string", "description": "Type of this phone/route (e.g. android, twilio, nexmo, etc)", "example": "android" }, "country": { "type": "string", "description": "2-letter country code (ISO 3166-1 alpha-2) where phone is from", "example": "TZ" }, "send_paused": { "type": "boolean", "description": "True if sending messages is currently paused, false if the phone can currently send messages", "example": false }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the phone was created in Telerivet", "example": 1390343779 }, "last_active_time": { "type": "integer", "format": "unix-timestamp", "description": "Approximate time this phone last connected to Telerivet", "example": 1390353800, "nullable": true }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this phone. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "project_id": { "type": "string", "description": "ID of the project this phone belongs to", "example": "PJ2ad0100821a98bea" }, "validate_recipient_numbers": { "type": "boolean", "description": "Set to true to check that recipient phone numbers appear to be valid before sending messages. Messages to invalid phone numbers will fail without being sent. Only applies to phones capable of sending messages.", "example": true }, "allowed_recipient_countries": { "type": "array", "items": { "type": "string" }, "description": "Array of 2-letter country codes (ISO 3166-1 alpha-2) to which this phone is allowed to send messages. When null, there is no restriction on recipient countries.", "nullable": true }, "sent_message_limit": { "type": "integer", "description": "Maximum number of messages that can be sent from this phone in a given period. When the sent_message_count reaches this limit, sending is automatically paused. Set to null to disable the limit.", "example": 1000, "nullable": true }, "sent_message_count": { "type": "integer", "description": "Number of messages sent from this phone since the counter was last reset (see sent_message_epoch). This property is not updated if sent_message_limit is null.", "example": 150 }, "sent_message_epoch": { "type": "integer", "format": "unix-timestamp", "description": "The UNIX timestamp when the sent_message_count was last reset to 0.", "example": 1720300000, "nullable": true }, "send_delay": { "type": "number", "description": "Number of seconds to wait after sending each message from this phone, to avoid exceeding carrier rate limits.", "example": 1.5, "nullable": true }, "timezone_id": { "type": "string", "description": "A string specifying the time zone that will be used when implementing quiet hours or estimating send times; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). When null, the project's default time zone is used.", "example": "America/Los_Angeles", "nullable": true }, "quiet_mode": { "type": "string", "description": "Controls behavior during quiet hours (see quiet_start/quiet_end). Possible values are 'off' (quiet hours disabled), 'delay' (messages are delayed until quiet hours end), or 'confirm' (requires manual confirmation to send during quiet hours).", "enum": [ "off", "delay", "confirm" ], "example": "delay" }, "quiet_start": { "type": "string", "description": "Time of day when quiet hours begin, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.", "example": "22:00", "nullable": true }, "quiet_end": { "type": "string", "description": "Time of day when quiet hours end, in HH:MM format (24-hour time) in the phone's time zone. Messages sent during quiet hours are delayed or require confirmation depending on quiet_mode. Only applicable when quiet_mode is not 'off'.", "example": "08:00", "nullable": true }, "battery": { "type": "integer", "description": "Current battery level, on a scale from 0 to 100, as of the last time the phone connected to Telerivet (only present for Android phones)", "example": 95, "nullable": true }, "charging": { "type": "boolean", "description": "True if the phone is currently charging, false if it is running on battery, as of the last time it connected to Telerivet (only present for Android phones)", "example": false, "nullable": true }, "internet_type": { "type": "string", "description": "String describing the current type of internet connectivity for an Android phone, for example WIFI or MOBILE (only present for Android phones)", "example": "WIFI", "nullable": true }, "app_version": { "type": "string", "description": "Currently installed version of Telerivet Android app (only present for Android phones)", "example": "3.1.17" }, "android_sdk": { "type": "integer", "description": "Android SDK level, indicating the approximate version of the Android OS installed on this phone; see [list of Android SDK levels](http://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) (only present for Android phones)", "example": 17, "nullable": true }, "mccmnc": { "type": "string", "description": "Code indicating the Android phone's current country (MCC) and mobile network operator (MNC); see [Mobile country code Wikipedia article](https://en.wikipedia.org/wiki/Mobile_country_code) (only present for Android phones). Note this is a string containing numeric digits, not an integer.", "example": "23203" }, "manufacturer": { "type": "string", "description": "Android phone manufacturer (only present for Android phones)", "example": "LGE" }, "model": { "type": "string", "description": "Android phone model (only present for Android phones)", "example": "Nexus 4" }, "send_limit": { "type": "integer", "description": "Maximum number of SMS messages per hour that can be sent by this Android phone. To increase this limit, install additional SMS expansion packs in the Telerivet Gateway app. (only present for Android phones)", "example": 900, "nullable": true }, "external_account_id": { "type": "string", "description": "Account ID for the external API (e.g. Twilio Account SID, Vonage API Key). Only present for routes that support external API configuration. See createPhone for the meaning of this field for each phone type.", "nullable": true }, "external_id": { "type": "string", "description": "External phone/resource ID within the external API account (if applicable). Only present for routes that support external API configuration.", "nullable": true }, "external_config": { "type": "object", "additionalProperties": true, "description": "Additional configuration settings specific to the phone_type. Only present for routes that support external API configuration. See createPhone for available settings for each phone type.", "nullable": true }, "external_setup": { "type": "object", "additionalProperties": true, "description": "Configuration info for routes that require manual webhook setup. Only present for routes that require manual configuration of callback URLs with the external provider. Contains URL properties for each webhook type that needs to be configured (e.g., `incoming_message_url`, `message_status_url`, `incoming_call_url`).", "nullable": true }, "external_secret": { "type": "string", "description": "Secret/API key for the external API (e.g. Twilio Auth Token, Vonage API Secret). Only applicable for routes that support external API configuration. Write-only; not returned by the API when retrieving a phone.", "nullable": true }, "url": { "type": "string", "description": "URL to this phone in the Telerivet web app", "example": "https://telerivet.com/p/asdf/phone/PN4d246818d0ecd1fa" } }, "description": "Represents a basic route (i.e. a phone or gateway) that you use to send/receive messages via Telerivet.\n\n Basic Routes were formerly referred to as \"Phones\" within Telerivet. API methods, parameters, and properties related to Basic Routes continue to use the term \"Phone\" to maintain backwards compatibility." }, "Route": { "type": "object", "properties": { "id": { "type": "string", "description": "Telerivet's internal ID for the route", "example": "RTed8af84c2679ac09" }, "name": { "type": "string", "description": "The name of the route", "example": "Custom Route" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this route. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "url": { "type": "string", "description": "URL to this route in the Telerivet web app", "example": "https://telerivet.com/p/asdf/route/RTed8af84c2679ac09" }, "project_id": { "type": "string", "description": "ID of the project this route belongs to", "example": "PJ2ad0100821a98bea" }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingAction" }, "description": "Array of routing action objects. Allowed action types: `use_phone`, `condition`." } }, "description": "Represents a custom route that can be used to send messages via one or more basic routes (phones).\n\nCustom Routes were formerly referred to simply as \"Routes\" within Telerivet. API methods, parameters, and properties related to Custom Routes continue to use the term \"Route\" to maintain backwards compatibility." }, "DataTable": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the data table", "example": "DTf9f77c9ba69cce50" }, "name": { "type": "string", "description": "Name of the data table", "example": "Poll Responses" }, "num_rows": { "type": "integer", "description": "Number of rows in the table. For performance reasons, this number may sometimes be out-of-date.", "example": 1032 }, "show_add_row": { "type": "boolean", "description": "Whether to allow adding or importing rows via the web app", "example": false }, "show_stats": { "type": "boolean", "description": "Whether to show summary charts (pie charts, bar charts, tables of top values) for this data table in the web app", "example": true }, "show_contact_columns": { "type": "boolean", "description": "Whether to show 'Contact Name' and 'Phone Number' columns in the web app", "example": true }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this data table. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "project_id": { "type": "string", "description": "ID of the project this data table belongs to", "example": "PJ2ad0100821a98bea" }, "url": { "type": "string", "description": "URL to this data table in the Telerivet web app", "example": "https://telerivet.com/p/asdf/data/Poll_20Responses" } }, "description": "Represents a custom data table that can store arbitrary rows.\n\n For example, poll services use data tables to store a row for each response.\n\n DataTables are schemaless -- each row simply stores custom variables. Each variable name is equivalent to a different \"column\" of the data table.\n Telerivet refers to these variables/columns as \"fields\", and automatically creates a new field for each variable name used in a row of the table." }, "DataRow": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the data row", "example": "DRd442e170d6133590" }, "contact_id": { "type": "string", "description": "ID of the contact this row is associated with (or null if not associated with any contact)", "example": "CTa1299c3d0e371023" }, "from_number": { "type": "string", "description": "Phone number that this row is associated with (or null if not associated with any phone number)", "example": "+16505550123" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this data row. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "The time this row was created in Telerivet", "example": 1395102559 }, "time_updated": { "type": "integer", "format": "unix-timestamp", "description": "The time this row was last updated in Telerivet", "example": 1395102578 }, "table_id": { "type": "string", "description": "ID of the table this data row belongs to", "example": "DTf9f77c9ba69cce50" }, "project_id": { "type": "string", "description": "ID of the project this data row belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents a row in a custom data table.\n\n For example, each response to a poll is stored as one row in a data table. If a poll has a question with ID 'q1', the verbatim response to that question would be stored in {sigil}row{dot}vars{dot}q1, and the response code would be stored in {sigil}row{dot}vars{dot}q1_code.\n\n Each custom variable name within a data row corresponds to a different column/field of the data table." }, "DataView": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the data view", "example": "DV81c9612b4b4d4c4e" }, "name": { "type": "string", "description": "Name of the data view", "example": "Completed Responses" }, "num_rows": { "type": "integer", "description": "Number of rows matching the view filter. For performance reasons, this number may sometimes be out-of-date.", "example": 122 }, "filters": { "type": "object", "additionalProperties": true, "description": "Key-value pairs of conditions that rows must match to be included in the view, in the same format as the `filters` parameter of table.createView" }, "table_id": { "type": "string", "description": "ID of the table this view belongs to", "example": "DTf9f77c9ba69cce50" }, "project_id": { "type": "string", "description": "ID of the project this view belongs to", "example": "PJ2ad0100821a98bea" }, "url": { "type": "string", "description": "URL to this view in the Telerivet web app", "example": "https://telerivet.com/p/asdf/data/Poll_20Responses?f[view]=DV81c9612b4b4d4c4e" } }, "description": "Represents a view of a data table, defined by a saved filter on the table's rows.\n\n The view's filter conditions cannot be changed after the view is created (although the view can be renamed or deleted).\n\n Telerivet will automatically store the count of rows matching each data view once a day, making it possible to retrieve historical statistics for the number of rows matching the filter." }, "Service": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the service", "example": "SVee45c8ae4e32889a" }, "name": { "type": "string", "description": "Name of the service", "example": "Poll Service" }, "service_type": { "type": "string", "description": "Type of the service.", "example": "messaging_poll" }, "active": { "type": "boolean", "description": "Whether the service is active or inactive. Inactive services are not automatically triggered and cannot be invoked via the API.", "example": true }, "priority": { "type": "integer", "description": "A number that determines the order that services are triggered when a particular event occurs (smaller numbers are triggered first). Any service can determine whether or not execution \"falls-through\" to subsequent services (with larger priority values) by setting the return_value variable within Telerivet's Rules Engine.", "example": 1 }, "contexts": { "type": "object", "additionalProperties": true, "description": "A key/value map where the keys are the names of contexts supported by this service (e.g. message, contact), and the values are themselves key/value maps where the keys are event names and the values are all true. (This structure makes it easy to test whether a service can be invoked for a particular context and event.)" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this service. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "url": { "type": "string", "description": "URL to this service in the Telerivet web app", "example": "https://telerivet.com/p/asdf/service/SVee45c8ae4e32889a" }, "url_edit": { "type": "string", "description": "URL to edit the service in the Telerivet web app", "example": "https://telerivet.com/p/asdf/service/SV2ad0100821a98bea/edit" }, "project_id": { "type": "string", "description": "ID of the project this service belongs to", "example": "PJ2ad0100821a98bea" }, "response_table_id": { "type": "string", "description": "ID of the data table where responses to this service will be stored", "example": "DTf9fe14d9c306aed9" }, "phone_ids": { "type": "string", "description": "IDs of phones (basic routes) associated with this service, or null if the service is associated with all routes. Only applies for service types that handle incoming messages, voice calls, or USSD sessions." }, "message_types": { "type": "array", "items": { "type": "string" }, "description": "Types of messages that this service handles. Only provided for service types that handle incoming messages.", "enum": [ "text", "call", "ussd" ] }, "table_ids": { "type": "string", "description": "IDs of data tables that this service applies to, or null if this service applies to all data tables. Only provided for data row services (`data_row_script` and `data_row_actions`)." }, "message_statuses": { "type": "array", "items": { "type": "string" }, "description": "Message statuses that this service handles. Only provided for `message_status_actions` services.", "enum": [ "sent", "delivered", "failed", "failed_queued", "not_delivered" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags used to organize this service. Each tag can be up to 32 characters in length." }, "apply_mode": { "type": "string", "description": "If apply_mode is `unhandled`, the service will not be triggered if another service has already handled the incoming message. If apply_mode is `always`, the service will always be triggered regardless of other services. Only applies to services that handle incoming messages.", "enum": [ "always", "unhandled" ] }, "contact_number_filter": { "type": "string", "description": "If contact_number_filter is `long_number`, this service will only be triggered if the contact phone number has at least 7 digits (ignoring messages from shortcodes and alphanumeric senders). If contact_number_filter is `all`, the service will be triggered for all contact phone numbers. Only applies to services that handle incoming messages.", "enum": [ "long_number", "all" ] }, "show_action": { "type": "boolean", "description": "Whether this service is shown in the 'Actions' menu within the Telerivet web app when the service is active. Only provided for service types that are manually triggered." }, "direction": { "type": "string", "description": "Determines whether the service handles incoming voice calls, outgoing voice calls, or both. Only applies to services that handle voice calls.", "enum": [ "incoming", "outgoing", "both" ] }, "webhook_url": { "type": "string", "description": "URL that a third-party can invoke to trigger this service. Only provided for services that are triggered by a webhook request." }, "is_custom_template": { "type": "boolean", "description": "Whether this service was created from a custom service template" } }, "description": "Represents an automated service on Telerivet, for example a poll, auto-reply, webhook service, etc.\n\n A service, generally, defines some automated behavior that can be invoked/triggered in a particular context, and may be invoked either manually or when a particular event occurs.\n\n Most commonly, services work in the context of a particular message, when the message is originally received by Telerivet." }, "ContactServiceState": { "type": "object", "properties": { "id": { "type": "string", "description": "Arbitrary string representing the contact's current state for this service, e.g. 'q1', 'q2', etc.", "example": "q1" }, "contact_id": { "type": "string", "description": "ID of the contact", "example": "CTa1299c3d0e371023" }, "service_id": { "type": "string", "description": "ID of the service", "example": "SVee45c8ae4e32889a" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this contact/service state. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the state was first created in Telerivet", "example": 1395617416 }, "time_updated": { "type": "integer", "format": "unix-timestamp", "description": "Time the state was last updated in Telerivet", "example": 1395617440 }, "project_id": { "type": "string", "description": "ID of the project this contact/service state belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents the current state of a particular contact for a particular Telerivet service.\n\n Some automated services (including polls) are 'stateful'. For polls, Telerivet needs to keep track of which question the contact is currently answering, and stores store the ID of each contact's current question (e.g. 'q1' or 'q2') as the ID of the contact's state for the poll service. Any type of conversation-like service will also need to store state for each contact.\n\n For this type of entity, the 'id' field is NOT a read-only unique ID (unlike all other types of entities). Instead it is an arbitrary string that identifies the contact's current state within your poll/conversation; many contacts may have the same state ID, and it may change over time. Additional custom fields may be stored in the 'vars'.\n\n Initially, the state 'id' for any contact is null. When saving the state, setting the 'id' to null is equivalent to resetting the state (so all 'vars' will be deleted); if you want to save custom variables, the state 'id' must be non-null.\n\n Many Telerivet services are stateless, such as auto-replies or keyword-based services where the behavior only depends on the current message, and not any previous messages sent by the same contact. Telerivet doesn't store any state for contacts that interact with stateless services." }, "MessageTemplate": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the message template", "example": "MTd34f8c1d71a3e2b4" }, "name": { "type": "string", "description": "Name of the template (max 127 characters)", "example": "Welcome Message" }, "content": { "type": "string", "description": "Content of the message template (max 2000 characters)", "example": "Hello, [[contact.name]]! Welcome to our service." }, "track_clicks": { "type": "boolean", "description": "If true, URLs in the content will be replaced with short links that track clicks when the template is used" }, "readonly": { "type": "boolean", "description": "True if the template cannot be modified or deleted (i.e., it was synchronized from a WhatsApp Business Account)", "example": false }, "short_link_params": { "type": "object", "additionalProperties": true, "description": "Custom parameters for short links (only if track_clicks is true)", "nullable": true }, "attachments": { "type": "array", "items": { "type": "string" }, "description": "List of attachment objects with file URLs", "nullable": true }, "route_params": { "type": "object", "additionalProperties": true, "description": "Route-specific parameters to use when sending messages with this template. \n\n 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.\n\n For more details, see Route-Specific Parameters.", "nullable": true }, "waba_id": { "type": "string", "description": "ID of the WhatsApp Business Account that this template is associated with (only present for WhatsApp templates)", "nullable": true }, "whatsapp_template": { "type": "object", "additionalProperties": true, "description": "For templates synchronized from a WhatsApp Business Account, contains the full template data from WhatsApp with properties including `id`, `name`, `language`, `status`, `category`, and `components`. The full format is defined in the [WhatsApp Template API documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/template-api#get-version-template-id). Only present for WhatsApp templates.", "nullable": true }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the template was created in Telerivet", "example": 1390343800 }, "time_updated": { "type": "integer", "format": "unix-timestamp", "description": "Time the template was last updated", "example": 1390343845 }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this template. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." }, "project_id": { "type": "string", "description": "ID of the project this template belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents a reusable message template that can be used when composing or scheduling messages.\n\n Message templates can include placeholder variables using double square brackets (e.g. `[[contact.name]]`) that are replaced with actual values when the message is sent. For available variables, see Variable Reference. The double square brackets may also include [filters](https://telerivet.com/api/rules_engine#filters) to transform variables, such as to set a default value.\n\n Templates synchronized from a WhatsApp Business Account are read-only and cannot be modified or deleted via the API.\n (When using Telerivet to send messages via a WhatsApp route, Telerivet tries to match the content of each outgoing message to one of these WhatsApp message templates. If a template matches, Telerivet sends a WhatsApp template message instead of a session message.)" }, "StoredFile": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the stored file", "example": "SF2c72e0be64f38ea9" }, "filename": { "type": "string", "description": "Filename of the stored file", "example": "image.jpg" }, "type": { "type": "string", "description": "MIME type of the file", "example": "image/jpeg" }, "size": { "type": "integer", "description": "Size of the file in bytes", "example": 482133 }, "description": { "type": "string", "description": "Description of the file", "nullable": true }, "category": { "type": "string", "description": "Category of the stored file", "enum": [ "outgoing_media", "incoming_media", "call_audio", "test_recording", "script_module", "icon" ], "example": "outgoing_media" }, "source": { "type": "string", "description": "How the stored file was created", "enum": [ "upload", "recording", "message", "api" ], "example": "api" }, "message_id": { "type": "string", "description": "ID of the message associated with this file, if any. Files associated with a message are deleted automatically when the message is deleted.", "example": "SM66bba24d8b6a3a25", "nullable": true }, "sha256": { "type": "string", "description": "SHA-256 hash of the file content (lowercase hex), if available", "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "nullable": true }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "Time the file was created in Telerivet", "example": 1751980000 }, "user_id": { "type": "string", "description": "ID of the Telerivet user who created the file (if applicable)", "example": "URba3e403e98f49735", "nullable": true }, "url": { "type": "string", "description": "URL where the file content can be downloaded. Note: this URL is temporary and may not be valid for more than 1 day; retrieve the stored file again to get a fresh URL." }, "thumbnail_url": { "type": "string", "description": "URL of a thumbnail image for video files, if available. Note: this URL is temporary and may not be valid for more than 1 day.", "nullable": true }, "project_id": { "type": "string", "description": "ID of the project this file belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents a file stored in a Telerivet project, such as a media attachment for outgoing messages.\n\n Stored files are also automatically created for media attachments for incoming messages.\n\n Files can be uploaded via project.uploadFile, then attached to outgoing messages by passing the file ID as a `file_id` item in the `media` parameter when sending a message or broadcast." }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the organization", "example": "ACa073512bd217d24e" }, "name": { "type": "string", "description": "Name of the organization", "example": "Example Organization" }, "timezone_id": { "type": "string", "description": "Billing quota time zone ID; see [List of tz database time zones Wikipedia article](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).", "example": "America/Los_Angeles" } }, "description": "Represents a Telerivet organization." }, "AirtimeTransaction": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the airtime transaction", "example": "ATb11111211217d11f" }, "to_number": { "type": "string", "description": "Destination phone number in international format (no leading +)", "example": "639123123123" }, "operator_name": { "type": "string", "description": "Operator name", "example": "Globe Philippines" }, "country": { "type": "string", "description": "Country code", "example": "PH" }, "time_created": { "type": "integer", "format": "unix-timestamp", "description": "The time that the airtime transaction was created on Telerivet's servers", "example": 1390347812 }, "transaction_time": { "type": "integer", "format": "unix-timestamp", "description": "The time that the airtime transaction was sent, or null if it has not been sent", "example": 1390347813 }, "status": { "type": "string", "description": "Current status of airtime transaction (`successful`, `failed`, `cancelled`, `queued`, `processing`, `submitted`, `pending_approval`, or `pending_payment`)", "enum": [ "successful", "failed", "cancelled", "queued", "processing", "submitted", "pending_approval", "pending_payment" ], "example": "successful" }, "status_text": { "type": "string", "description": "Error or success message returned by airtime provider, if available", "example": "Transaction successful" }, "value": { "type": "string", "description": "Value of airtime sent to destination phone number, in units of value_currency", "example": 25 }, "value_currency": { "type": "string", "description": "Currency code of price", "example": "PHP" }, "price": { "type": "string", "description": "Price charged for airtime transaction, in units of price_currency", "example": 0.63 }, "price_currency": { "type": "string", "description": "Currency code of price", "example": "USD" }, "contact_id": { "type": "string", "description": "ID of the contact the airtime was sent to", "example": "CTa01111211217d24e" }, "service_id": { "type": "string", "description": "ID of the service that sent the airtime", "example": "SVb12345211217d35f" }, "project_id": { "type": "string", "description": "ID of the project that the airtime transaction belongs to", "example": "PJ012345211217c11a" }, "external_id": { "type": "string", "description": "The ID of this transaction from an external airtime gateway provider, if available.", "example": "GLYV2R8GHY8LS17Y0S0G" }, "user_id": { "type": "string", "description": "ID of the Telerivet user who sent the airtime transaction (if applicable)", "example": "URba3e403e98f49735" }, "vars": { "type": "object", "additionalProperties": true, "description": "Custom variables stored for this transaction. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _.\n Values may be strings, numbers, or boolean (true/false).\n String values may be up to 4096 bytes in length when encoded as UTF-8.\n Up to 100 variables are supported per object.\n Setting a variable to null will delete the variable." } }, "description": "Represents a transaction where airtime is sent to a mobile phone number. This also is used to represent non-airtime value transfers such as data bundles or gift cards.\n\nTo send airtime, first [create a Custom Actions service to send a particular amount of airtime](https://telerivet.com/dashboard/add_service?subtype_id=main.service.rules.contact&action_id=main.rule.sendairtime), then trigger the service using service.invoke, project.sendBroadcast, or project.scheduleMessage." }, "Webhook": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the webhook", "example": "WH4f3dac27154653e0" }, "url": { "type": "string", "description": "URL that webhook requests are sent to", "example": "https://example.com/webhook" }, "secret": { "type": "string", "description": "Secret included with webhook requests for authentication (sent as HTTP basic auth password with username 'telerivet')", "example": "my-webhook-secret" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Array of event types that trigger this webhook. Possible values: `send_status` (message status updates), `send_broadcast` (broadcast sent), `contact_update` (contact added/updated/deleted), `message_metadata` (message metadata updated)" }, "project_id": { "type": "string", "description": "ID of the project this webhook belongs to", "example": "PJ2ad0100821a98bea" } }, "description": "Represents a webhook that is triggered when specific events occur within a project.\n\n Webhooks allow your server to receive HTTP POST requests when certain events happen, such as when a message's status changes or when a contact is updated.\n\n When an event occurs that matches a webhook's event types, Telerivet will send an HTTP POST request to the webhook URL with information about the event. For more information about the webhook request format, see the [Webhook API](https://telerivet.com/api/webhook) documentation.\n\n Note: The Webhook object is not used for notifying your server when incoming messages are received. To notify a URL when incoming messages are received, you can configure a webhook by creating a Service with type incoming_message_webhook." } }, "responses": { "BadRequest": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Invalid or missing API key or Bearer token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "tags": [ { "name": "AirtimeTransaction", "description": "Airtime transactions record mobile airtime/data top-ups sent to contacts." }, { "name": "Campaign" }, { "name": "Contact", "description": "Contacts represent people you communicate with. Each contact has a phone number and can store custom variables." }, { "name": "DataTable", "description": "Data tables store structured data that can be queried and updated via the API or automation rules." }, { "name": "Group", "description": "Groups are collections of contacts used for organizing and bulk messaging." }, { "name": "Label", "description": "Labels categorize and organize messages for filtering and reporting." }, { "name": "Message", "description": "Messages are SMS, MMS, voice calls, or other communications sent or received through Telerivet." }, { "name": "MessageTemplate" }, { "name": "Organization", "description": "Organizations group multiple projects under a single billing account." }, { "name": "Phone", "description": "Phones (basic routes) are channels for sending/receiving messages via specific providers or phone numbers." }, { "name": "Project", "description": "Projects are workspaces that contain contacts, messages, and automation rules. Most API operations require a project_id." }, { "name": "ScheduledMessage", "description": "Scheduled messages are queued to be sent at a future time." }, { "name": "Service", "description": "Services are automation rules that trigger actions when messages are received or other events occur." }, { "name": "StoredFile" }, { "name": "Task", "description": "Tasks represent background operations like imports, exports, or bulk updates." }, { "name": "Webhook" }, { "name": "Webhooks", "description": "Webhooks are HTTP POST requests that Telerivet sends to YOUR server when events occur. Unlike the REST API (where you call Telerivet), webhooks allow Telerivet to notify you of events in real-time. Configure webhook URLs in Project Settings or by creating a Webhook service." } ], "externalDocs": { "description": "Cloud Script API Reference (TypeScript declarations with code examples)", "url": "https://api.telerivet.com/script.d.ts" }, "webhooks": { "incomingMessage": { "post": { "summary": "Incoming message received", "description": "Telerivet sends this webhook when incoming message received.\n\n**Setup:** Create a Webhook service in your project, or use the REST API to create a service with `service_type: webhook`.\n\n**Request format:** POST with `application/x-www-form-urlencoded` body.", "operationId": "webhookIncomingMessage", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WebhookIncomingMessage" } } }, "description": "Incoming message data (sent as form-urlencoded POST parameters)" }, "responses": { "200": { "description": "Webhook processed successfully. Optionally return JSON to send autoreplies or update variables.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } } } } }, "sendStatus": { "post": { "summary": "Outgoing message status changed", "description": "Telerivet sends this webhook when outgoing message status changed.\n\n**Setup:** Enable 'Message status notifications' in Project Settings, or specify `status_url` when sending a message.\n\n**Request format:** POST with `application/x-www-form-urlencoded` body.", "operationId": "webhookSendStatus", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WebhookSendStatus" } } } }, "responses": { "200": { "description": "Webhook processed successfully" } } } }, "sendBroadcast": { "post": { "summary": "Broadcast sent", "description": "Telerivet sends this webhook when broadcast sent.\n\n**Setup:** Enable 'Broadcast sent' webhook in Project Settings.\n\n**Request format:** POST with `application/x-www-form-urlencoded` body.", "operationId": "webhookSendBroadcast", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WebhookBroadcast" } } } }, "responses": { "200": { "description": "Webhook processed successfully" } } } }, "contactUpdate": { "post": { "summary": "Contact added, updated, or deleted", "description": "Telerivet sends this webhook when contact added, updated, or deleted.\n\n**Setup:** Enable 'Contact added or updated' webhook in Project Settings.\n\n**Request format:** POST with `application/x-www-form-urlencoded` body.\n\n**Note:** Not triggered for changes made via REST API or Cloud Script API.", "operationId": "webhookContactUpdate", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WebhookContactUpdate" } } } }, "responses": { "200": { "description": "Webhook processed successfully" } } } }, "messageMetadata": { "post": { "summary": "Message metadata updated", "description": "Telerivet sends this webhook when message metadata updated.\n\n**Setup:** Enable 'Message metadata updated' webhook in Project Settings.\n\n**Request format:** POST with `application/x-www-form-urlencoded` body.", "operationId": "webhookMessageMetadata", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/WebhookMessageMetadata" } } } }, "responses": { "200": { "description": "Webhook processed successfully" } } } } } }