Service

Create a service

Creates a new automated service.

Only certain types of automated services can be created via the API. Other types of services can only be created via the web app.

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.

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.

post/v1/projects/{project_id}/services

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/services
  • Auth: one of:
    • HTTP basic
    • OAuth 2 (authorization code, authorization URL https://telerivet.com/oauth/authorize, token URL https://api.telerivet.com/oauth/token)

Path parameters

project_idstring required

ID of the Project

Request body

service_type'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' required

Type of service to create. See x-service-types in info section for all types and their configurations.

namestring

Name of the service (auto-generated if not provided)

activeboolean

Whether the service is active

varsobject

Custom variables for the service

phone_idsstring[]

Limit to specific phone/route IDs (null for all)

message_typesstring[]

Message types this service handles. Only applies to services that handle incoming messages.

direction'incoming' | 'outgoing' | 'both'

Direction of messages/calls this service handles. Only applies to voice services.

table_idsstring[]

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_statusesstring[]

Array of message statuses to handle. Only applies to message_status_actions service type.

tagsstring[]

Array of tags for categorizing the service (max 10 tags, max 32 characters each).

priorityinteger

Execution priority (lower numbers run first)

Example request

{
  "config": {
    "actions": [
      {
        "type": "reply",
        "body": {
          "content": "Hello, [[contact.name]]."
        }
      }
    ],
    "subroutines": [
      {
        "actions": [
          {
            "type": "add_contact_to_group",
            "group_name": "subscribers"
          }
        ]
      }
    ],
    "response_handlers": [
      {
        "actions": [
          {
            "type": "reply",
            "body": {
              "content": "Hello, [[contact.name]]."
            }
          }
        ]
      }
    ]
  }
}

Response

Successful response

idstring

ID of the service

namestring

Name of the service

service_typestring

Type of the service.

activeboolean

Whether the service is active or inactive. Inactive services are not automatically triggered and cannot be invoked via the API.

priorityinteger

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.

contextsobject

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.)

varsobject

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 _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.

urlstring

URL to this service in the Telerivet web app

url_editstring

URL to edit the service in the Telerivet web app

project_idstring

ID of the project this service belongs to

response_table_idstring

ID of the data table where responses to this service will be stored

phone_idsstring

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_typesstring[]

Types of messages that this service handles. Only provided for service types that handle incoming messages.

table_idsstring

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_statusesstring[]

Message statuses that this service handles. Only provided for message_status_actions services.

tagsstring[]

Tags used to organize this service. Each tag can be up to 32 characters in length.

apply_mode'always' | 'unhandled'

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.

contact_number_filter'long_number' | 'all'

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.

show_actionboolean

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'incoming' | 'outgoing' | 'both'

Determines whether the service handles incoming voice calls, outgoing voice calls, or both. Only applies to services that handle voice calls.

webhook_urlstring

URL that a third-party can invoke to trigger this service. Only provided for services that are triggered by a webhook request.

is_custom_templateboolean

Whether this service was created from a custom service template

solution_idstring nullable

ID of the solution that this service belongs to, if any

Example response

{
  "id": "SVee45c8ae4e32889a",
  "name": "Poll Service",
  "service_type": "messaging_poll",
  "active": true,
  "priority": 1,
  "url": "https://telerivet.com/p/asdf/service/SVee45c8ae4e32889a",
  "url_edit": "https://telerivet.com/p/asdf/service/SV2ad0100821a98bea/edit",
  "project_id": "PJ2ad0100821a98bea",
  "response_table_id": "DTf9fe14d9c306aed9",
  "solution_id": "SO2ad0100821a98bea"
}

Changes

No recorded changes to this operation across all 1 revision of this API.