Update an agent's voice

PATCH

agents

{id}

voice

Update an agent's voice

curl --request PATCH \
  --url https://api.us.phonely.ai/v1/agents/{id}/voice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "background_sound": "<string>",
  "background_volume": 0.5,
  "languages": [
    "<string>"
  ],
  "pronunciations": [
    {
      "word": "<string>",
      "ipa": "<string>",
      "pronunciation": "<string>"
    }
  ],
  "speed": 123,
  "transcription_keywords": [
    "<string>"
  ],
  "voice_id": "<string>"
}
'

import requests

url = "https://api.us.phonely.ai/v1/agents/{id}/voice"

payload = {
    "background_sound": "<string>",
    "background_volume": 0.5,
    "languages": ["<string>"],
    "pronunciations": [
        {
            "word": "<string>",
            "ipa": "<string>",
            "pronunciation": "<string>"
        }
    ],
    "speed": 123,
    "transcription_keywords": ["<string>"],
    "voice_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    background_sound: '<string>',
    background_volume: 0.5,
    languages: ['<string>'],
    pronunciations: [{word: '<string>', ipa: '<string>', pronunciation: '<string>'}],
    speed: 123,
    transcription_keywords: ['<string>'],
    voice_id: '<string>'
  })
};

fetch('https://api.us.phonely.ai/v1/agents/{id}/voice', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.us.phonely.ai/v1/agents/{id}/voice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'background_sound' => '<string>',
    'background_volume' => 0.5,
    'languages' => [
        '<string>'
    ],
    'pronunciations' => [
        [
                'word' => '<string>',
                'ipa' => '<string>',
                'pronunciation' => '<string>'
        ]
    ],
    'speed' => 123,
    'transcription_keywords' => [
        '<string>'
    ],
    'voice_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.us.phonely.ai/v1/agents/{id}/voice"

	payload := strings.NewReader("{\n  \"background_sound\": \"<string>\",\n  \"background_volume\": 0.5,\n  \"languages\": [\n    \"<string>\"\n  ],\n  \"pronunciations\": [\n    {\n      \"word\": \"<string>\",\n      \"ipa\": \"<string>\",\n      \"pronunciation\": \"<string>\"\n    }\n  ],\n  \"speed\": 123,\n  \"transcription_keywords\": [\n    \"<string>\"\n  ],\n  \"voice_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.us.phonely.ai/v1/agents/{id}/voice")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"background_sound\": \"<string>\",\n  \"background_volume\": 0.5,\n  \"languages\": [\n    \"<string>\"\n  ],\n  \"pronunciations\": [\n    {\n      \"word\": \"<string>\",\n      \"ipa\": \"<string>\",\n      \"pronunciation\": \"<string>\"\n    }\n  ],\n  \"speed\": 123,\n  \"transcription_keywords\": [\n    \"<string>\"\n  ],\n  \"voice_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.us.phonely.ai/v1/agents/{id}/voice")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"background_sound\": \"<string>\",\n  \"background_volume\": 0.5,\n  \"languages\": [\n    \"<string>\"\n  ],\n  \"pronunciations\": [\n    {\n      \"word\": \"<string>\",\n      \"ipa\": \"<string>\",\n      \"pronunciation\": \"<string>\"\n    }\n  ],\n  \"speed\": 123,\n  \"transcription_keywords\": [\n    \"<string>\"\n  ],\n  \"voice_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "agent_id": "<string>",
  "background_sound": "<string>",
  "background_volume": 123,
  "languages": [
    "<string>"
  ],
  "object": "agent_voice",
  "pronunciations": [
    {
      "ipa": "<string>",
      "pronunciation": "<string>",
      "word": "<string>"
    }
  ],
  "speed": 123,
  "transcription_keywords": [
    "<string>"
  ],
  "voice_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

An org API key: Authorization: Bearer phk_…

Headers

If-Match

string | null

The ETag from your last read: the change is made only if the resource still has it, otherwise 412. Optional, except that a change replacing a list needs it (428 without it).

Phonely-Organization

string | null

Optional. Must be the key's org.

Path Parameters

string

required

The agent's ID.

Body

application/json

What to change. Only the fields sent change; a list sent replaces the stored one, so send If-Match.

background_sound

string | null

Known values: off, office, soft_office. More can be added, so handle values you don't recognize.

background_volume

number | null

The background sound volume, above 0, up to 1. null resets it to the 0.2 default.

Required range: 0 < x <= 1

languages

string[] | null

The languages the agent listens for, as language codes, in order. Only those the transcriber and voice support. null resets them to the voice's language or the transcriber's default.

pronunciations

PronunciationUpdate · object[] | null

All the pronunciations: words left out are removed, and null removes them all.

Show child attributes

speed

number | null

How fast the voice speaks, where 1.0 is its natural pace, within the voice's provider's range (0.5 to 1.5 for most voices). null resets it to 1.0.

transcription_keywords

string[] | null

All the words the agent listens for especially closely: each once, not blank.

voice_id

string | null

The voice to speak with: a public voice, or one of your organization's. Changing it keeps only the languages it speaks, and brings speed into its provider's range.

Response

Successful Response

How an agent sounds and what it listens for.

agent_id

string

required

The agent's ID.

background_sound

string

required

Ambient sound played behind the voice. Known values: off, office, soft_office. More can be added, so handle values you don't recognize.

background_volume

number

required

The background sound volume, from 0 to 1.

languages

string[] | null

required

The languages the agent listens for, as language codes such as en or es. null when none is chosen: the transcriber's default languages apply.

object

string

default:agent_voice

required

The type of this object, always agent_voice.

Allowed value: "agent_voice"

pronunciations

Pronunciation · object[]

required

How the agent should say particular words.

Show child attributes

speed

number

required

How fast the voice speaks, where 1.0 is its natural pace.

transcription_keywords

string[]

required

Words the agent listens for especially closely, such as names or product terms.

voice_id

string | null

required

The voice the agent speaks with. null when none is chosen.

⌘I

Update an agent's voice

curl --request PATCH \
  --url https://api.us.phonely.ai/v1/agents/{id}/voice \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "background_sound": "<string>",
  "background_volume": 0.5,
  "languages": [
    "<string>"
  ],
  "pronunciations": [
    {
      "word": "<string>",
      "ipa": "<string>",
      "pronunciation": "<string>"
    }
  ],
  "speed": 123,
  "transcription_keywords": [
    "<string>"
  ],
  "voice_id": "<string>"
}
'

import requests

url = "https://api.us.phonely.ai/v1/agents/{id}/voice"

payload = {
    "background_sound": "<string>",
    "background_volume": 0.5,
    "languages": ["<string>"],
    "pronunciations": [
        {
            "word": "<string>",
            "ipa": "<string>",
            "pronunciation": "<string>"
        }
    ],
    "speed": 123,
    "transcription_keywords": ["<string>"],
    "voice_id": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    background_sound: '<string>',
    background_volume: 0.5,
    languages: ['<string>'],
    pronunciations: [{word: '<string>', ipa: '<string>', pronunciation: '<string>'}],
    speed: 123,
    transcription_keywords: ['<string>'],
    voice_id: '<string>'
  })
};

fetch('https://api.us.phonely.ai/v1/agents/{id}/voice', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.us.phonely.ai/v1/agents/{id}/voice",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'background_sound' => '<string>',
    'background_volume' => 0.5,
    'languages' => [
        '<string>'
    ],
    'pronunciations' => [
        [
                'word' => '<string>',
                'ipa' => '<string>',
                'pronunciation' => '<string>'
        ]
    ],
    'speed' => 123,
    'transcription_keywords' => [
        '<string>'
    ],
    'voice_id' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.us.phonely.ai/v1/agents/{id}/voice"

	payload := strings.NewReader("{\n  \"background_sound\": \"<string>\",\n  \"background_volume\": 0.5,\n  \"languages\": [\n    \"<string>\"\n  ],\n  \"pronunciations\": [\n    {\n      \"word\": \"<string>\",\n      \"ipa\": \"<string>\",\n      \"pronunciation\": \"<string>\"\n    }\n  ],\n  \"speed\": 123,\n  \"transcription_keywords\": [\n    \"<string>\"\n  ],\n  \"voice_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.us.phonely.ai/v1/agents/{id}/voice")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"background_sound\": \"<string>\",\n  \"background_volume\": 0.5,\n  \"languages\": [\n    \"<string>\"\n  ],\n  \"pronunciations\": [\n    {\n      \"word\": \"<string>\",\n      \"ipa\": \"<string>\",\n      \"pronunciation\": \"<string>\"\n    }\n  ],\n  \"speed\": 123,\n  \"transcription_keywords\": [\n    \"<string>\"\n  ],\n  \"voice_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.us.phonely.ai/v1/agents/{id}/voice")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"background_sound\": \"<string>\",\n  \"background_volume\": 0.5,\n  \"languages\": [\n    \"<string>\"\n  ],\n  \"pronunciations\": [\n    {\n      \"word\": \"<string>\",\n      \"ipa\": \"<string>\",\n      \"pronunciation\": \"<string>\"\n    }\n  ],\n  \"speed\": 123,\n  \"transcription_keywords\": [\n    \"<string>\"\n  ],\n  \"voice_id\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "agent_id": "<string>",
  "background_sound": "<string>",
  "background_volume": 123,
  "languages": [
    "<string>"
  ],
  "object": "agent_voice",
  "pronunciations": [
    {
      "ipa": "<string>",
      "pronunciation": "<string>",
      "word": "<string>"
    }
  ],
  "speed": 123,
  "transcription_keywords": [
    "<string>"
  ],
  "voice_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "details": [
      {
        "field": "<string>",
        "issue": "<string>",
        "message": "<string>"
      }
    ],
    "message": "<string>",
    "request_id": "<string>"
  }
}

API v1

API v1 endpoints

Legacy API

Web SDK

Authorizations

Headers

Path Parameters

Body

Response