---
title: "Invoke a service"
method: POST
path: "/v1/projects/{project_id}/services/{id}/invoke"
tags: ["Service"]
---

# Invoke a service

`POST /v1/projects/{project_id}/services/{id}/invoke`

## Request

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

Manually invoke this service in a particular context.

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

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

## Path parameters

- `project_id` string, required
- `id` string, required

## Request body

- object
  - `context` 'message' | 'call' | 'ussd_session' | 'row' | 'contact' | 'project' | 'airtime_transaction', required: The name of the context in which this service is invoked
  - `event` string: The name of the event that is triggered (must be supported by this service)
  - `message_id` string: The ID of the message this service is triggered for
  - `contact_id` string: The ID of the contact this service is triggered for (either `contact_id` or `phone_number` is required if `context` is 'contact')
  - `phone_number` string: 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` string: The ID of the data row this service is triggered for
  - `variables` object: 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` string: The ID of the phone or route that the service will use for sending messages by default
  - `async` boolean: If set to true, the service will be invoked asynchronously. By default, queued services will be invoked one at a time for each project.

## Response `200`

Successful response

- object
  - `return_value` string: Return value of the service. May be any JSON type (boolean, number, string, array, object, or null). (Undefined if async=true.)
  - `log_entries` string[]: Array of log entry strings generated by the service. (Undefined if async=true.)
  - `errors` string[]: Array of error message strings generated by the service. (Undefined if async=true.)
  - `sent_messages` object[]: Array of messages sent by the service.
  - `airtime_transactions` object[]: Array of airtime transactions sent by the service (Undefined if async=true.)

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)