Service Communication

Call other services from your handler.

Your Restate handler can call other handlers in three ways:

• Request-response calls: Call and wait for a response
• One-way messages: Send a message and continue
• Delayed messages: Send a message after a delay

To call a service from an external application, see the HTTP, Kafka, or SDK Clients documentation.

Learn how Restate how it works

Request-response calls

To call a Restate handler and wait for its result:

// To call a Service:
const svcResponse = await ctx.serviceClient(myService).myHandler("Hi");

// To call a Virtual Object:
const objResponse = await ctx
  .objectClient(myObject, "Mary")
  .myHandler("Hi");

// To call a Workflow:
// `run` handler — can only be called once per workflow ID
const wfResponse = await ctx
  .workflowClient(myWorkflow, "wf-id")
  .run("Hi");
// Other handlers can be called anytime within workflow retention
const result = await ctx
  .workflowClient(myWorkflow, "wf-id")
  .interactWithWorkflow();

Use generic calls when you don’t have the service definition or need dynamic service names:

const response = await ctx.genericCall({
  service: "MyObject",
  method: "myHandler",
  parameter: "Hi",
  key: "Mary", // drop this for Service calls
  inputSerde: restate.serde.json,
  outputSerde: restate.serde.json,
});

Workflow retention

After a workflow’s run handler completes, other handlers can still be called for up to 24 hours (default). Update this via the service configuration.

Request-response calls between exclusive handlers of Virtual Objects may lead to deadlocks:

• Cross deadlock: A → B and B → A (same keys).
• Cycle deadlock: A → B → C → A.

Use the UI or CLI to cancel and unblock deadlocked invocations.

Sending messages

To send a message to another Restate handler without waiting for a response:

// To message a Service:
ctx.serviceSendClient(myService).myHandler("Hi");

// To message a Virtual Object:
ctx.objectSendClient(myObject, "Mary").myHandler("Hi");

// To message a Workflow:
// `run` handler — can only be called once per workflow ID
ctx.workflowSendClient(myWorkflow, "wf-id").run("Hi");
// Other handlers can be called anytime within workflow retention
ctx.workflowSendClient(myWorkflow, "wf-id").interactWithWorkflow();

Restate handles message delivery and retries, so the handler can complete and return without waiting for the message to be processed.

Use generic send when you don’t have the service definition:

ctx.genericSend({
  service: "MyService",
  method: "myHandler",
  parameter: "Hi",
  inputSerde: restate.serde.json,
});

Calls to a Virtual Object execute in order of arrival, serially. Example:

ctx.objectSendClient(myObject, "Mary").myHandler("I'm call A");
ctx.objectSendClient(myObject, "Mary").myHandler("I'm call B");

Call A is guaranteed to execute before B. However, other invocations may interleave between A and B.

Delayed messages

To send a message after a delay:

// To message a Service with a delay:
ctx
  .serviceSendClient(myService)
  .myHandler("Hi", restate.rpc.sendOpts({ delay: { hours: 5 } }));

// To message a Virtual Object with a delay:
ctx
  .objectSendClient(myObject, "Mary")
  .myHandler("Hi", restate.rpc.sendOpts({ delay: { hours: 5 } }));

// To message a Workflow with a delay:
ctx
  .workflowSendClient(myWorkflow, "Mary")
  .run("Hi", restate.rpc.sendOpts({ delay: { hours: 5 } }));

Use generic send with a delay when you don’t have the service definition:

ctx.genericSend({
  service: "MyService",
  method: "myHandler",
  parameter: "Hi",
  inputSerde: restate.serde.json,
  delay: { seconds: 5 },
});

Learn how this is different from sleeping and then sending a message.

Using an idempotency key

To prevent duplicate executions of the same call, add an idempotency key:

// For request-response
const response = await ctx.serviceClient(myService).myHandler(
  "Hi",
  restate.rpc.opts({
    idempotencyKey: "my-idempotency-key",
  })
);
// For sending a message
ctx.serviceSendClient(myService).myHandler(
  "Hi",
  restate.rpc.sendOpts({
    idempotencyKey: "my-idempotency-key",
  })
);

Restate automatically deduplicates calls made during the same handler execution, so there’s no need to provide an idempotency key in that case. However, if multiple handlers might call the same service independently, you can use an idempotency key to ensure deduplication across those calls.

Attach to an invocation

To wait for or get the result of a previously sent message:

const handle = ctx.serviceSendClient(myService).myHandler(
  "Hi",
  restate.rpc.sendOpts({
    idempotencyKey: "my-idempotency-key",
  })
);
const invocationId = await handle.invocationId;

// Later...
const response = ctx.attach(invocationId);

• With an idempotency key: Wait for completion and retrieve the result.
• Without an idempotency key: Can only wait, not retrieve the result.

Signals

Signals let invocations communicate directly with each other: one invocation waits for a named signal, and any other handler can resolve or reject it by referencing the target invocation’s ID.

Waiting for a signal (inside the invocation that wants to pause):

// Suspend until another handler sends a signal named "approved"
const approved = await ctx.signal<boolean>("approved");

Sending a signal (from another handler that knows the target invocation’s ID):

// Get a reference to the target invocation
const target = ctx.invocation(targetInvocationId);

// Resolve the signal with a value — wakes the waiting handler
target.signal<boolean>("approved").resolve(true);

// Or reject it — wakes the waiting handler with a terminal error
target.signal("approved").reject("Request denied");

The target invocation’s ID is available via ctx.request().id. Pass it to other handlers using state, awakeables, or any other mechanism you prefer.

Each invocation can wait on multiple distinct signal names at the same time. Signals are scoped to the invocation — the same name on different invocations is independent.

Signals require restate-server 1.7 with RESTATE_EXPERIMENTAL_ENABLE_PROTOCOL_V7=true enabled.

InvocationReference

ctx.invocation(invocationId) returns an InvocationReference that lets you interact with any other invocation by its ID:

const ref = ctx.invocation(targetInvocationId);

// Send a signal
ref.signal<boolean>("approved").resolve(true);

// Cancel the target invocation
ref.cancel();

// Attach and wait for the target invocation's result
const result = await ref.attach<string>();

Cancel an invocation

To cancel a running handler, use InvocationReference:

ctx.invocation(targetInvocationId).cancel();

Or using the legacy ctx.cancel() (deprecated):

const handle = ctx.serviceSendClient(myService).myHandler("Hi");
const invocationId = await handle.invocationId;

// Cancel the invocation
ctx.cancel(invocationId);

Advanced: sharing service type definitions

When calling services, you need access to their type definitions for type safety. Here are four approaches to share service definitions without exposing implementation details:

Option 1: Export type-only service definition

Export only the service type information from where you define your service:

export const myService = restate.service({
  name: "MyService",
  handlers: {
    myHandler: async (ctx: restate.Context, greeting: string) => {
      return `${greeting}!`;
    },
  },
});

export type MyService = typeof myService;

Import and use this definition in calling handlers:

const response = await ctx
  .serviceClient<MyService>({ name: "MyService" })
  .myHandler("Hi");

Option 2: Define service interface manually

Create a TypeScript interface matching the service’s handler signatures. Useful when the service is in a different language or when you can’t import the type definition:

interface MyService {
  myHandler(ctx: unknown, greeting: string): Promise<string>;
}
const response = await ctx
  .serviceClient<MyService>({ name: "MyService" })
  .myHandler("Hi");

Option 3: Import as dev dependency

When your service is published as a separate package, import it as a dev dependency to access its types:

// import type { MyService } from "my-service-package";

const response = await ctx
  .serviceClient<MyService>({ name: "MyService" })
  .myHandler("Hi");

See also

• SDK Clients: Call Restate services from external applications
• Error Handling: Handle failures and terminal errors in service calls
• Durable Timers: Implement timeouts for your service calls
• Serialization: Customize how data is serialized between services
• Sagas: Roll back or compensate for canceled service calls.