---
title: "Set the assistant"
method: PUT
path: "/assistant"
tags: ["Assistant"]
---

# Set the assistant

`PUT /assistant`

## Request

- Base URL: `https://api.hypamoon.com/api/v1`
- URL: `https://api.hypamoon.com/api/v1/assistant`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://app.hypamoon.com/oauth/authorize`, token URL `https://api.hypamoon.com/oauth/token`, scopes: `assistant:write`)

One assistant per project. PUT replaces all fields; any field you leave out reverts to its default. The greeting is fixed: it comes from your project name and always says the caller is talking to a digital assistant; sending greeting returns 422.

## Request body

- AssistantInput: PUT replaces all fields: a field you leave out goes back to its default.
  - `voice` 'saar' | 'fenna' | 'merel' | 'julia' | 'roos' | 'tim' | 'bram' | 'daan' | 'ruben' | 'ava' | 'nora' | 'liam' | 'owen' | 'lena' | 'mara' | 'jonas' | 'felix' | 'chloe' | 'manon' | 'hugo' | 'theo' | 'lucia' | 'elena' | 'pablo' | 'diego': The voice. It must speak the language: nl saar, fenna, merel, julia, roos, tim, bram, daan, ruben; en ava, nora, liam, owen; de lena, mara, jonas, felix; fr chloe, manon, hugo, theo; es lucia, elena, pablo, diego. Case does not matter. Default: the first voice of the language.
  - `language` 'nl' | 'en' | 'de' | 'fr' | 'es': The language the assistant opens and speaks in: en (English), nl (Dutch), de (German), fr (French) or es (Spanish). The greeting follows it. Default: the language of the country of your first number (Dutch while the project has no number yet).
  - `languages` string[]: The languages your callers speak; language always comes first. One language is the most reliable, because speech recognition never has to guess. Two or more switch it to multi, which follows the caller sentence by sentence, and the assistant switches with them. auto and multi are not accepted. Default: [language].
  - `instructions` string: What the assistant does, as free text. Default empty.
  - `website` string, nullable: Optional. We read the page and use it for opening hours, address and services. Must be a public web address.

## Response `200`

The assistant as saved.

- AssistantSaved: The assistant as saved.
  - `configured` boolean, required: Whether the assistant was ever set up with PUT /assistant.
  - `voice` string, nullable, required: The voice, like ava. It speaks the language.
  - `language` string, required: The language the assistant opens and speaks in, like en.
  - `languages` string[], required: The languages your callers speak, with language first.
  - `speech_recognition` string, required: The language of speech recognition: the one language, or multi when there are two or more.
  - `instructions` string, required: What the assistant does: your instructions.
  - `website` string, nullable, required: The website the assistant reads for opening hours, address and services.
  - `greeting` string, required: The fixed greeting, in the language. It follows from the project name and always says the caller is talking to a digital assistant.
  - `synced_at` string, date-time, nullable, required: When the assistant was last updated at the carrier.
  - `sync` 'synced' | 'failed' | 'skipped_test_mode', required: synced when the assistant was updated right away; failed when not. Your settings are saved either way and applied with the next PUT. skipped_test_mode with a test key: a test project has no live assistant.
  - `call_plan` 'added' | 'in_plan' | 'not_in_plan', required: added: the project only had the default plan (voicemail), so it now has a call plan where the assistant answers every call, with voicemail if the assistant is not available. in_plan: the call plan already sends calls to the assistant. not_in_plan: your own call plan does not use the assistant yet; add an ai_agent node with PUT /numbers/{id}/call-plan.
  - `next_step` string, required: What to do next.
  - `user_message` string, required: A sentence you can show the user as it is.

## Other responses

- `400`: Bad Request: invalid_json.
- `401`: Unauthorized: unauthorized, missing_api_key, invalid_api_key, api_key_revoked, project_deleted.
- `403`: Forbidden: project_not_enabled, key_mode_mismatch, missing_scope, verification_required.
- `409`: Conflict: version_conflict.
- `422`: Unprocessable Content: validation_failed.
- `429`: Too Many Requests: rate_limited.
- `500`: Internal Server Error: internal_error.
- `503`: Service Unavailable: service_unavailable.

---

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