Set prompt

Set the AI receptionist prompt

curl --request PUT \
  --url https://api.withallo.com/v2/api/numbers/{number}/agent/prompt \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sections": [
    {
      "content": "<string>",
      "fields": [
        {
          "label": "Email",
          "question": "What is the best email to send the quote to?",
          "complete_when": "a valid email address is given"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.withallo.com/v2/api/numbers/{number}/agent/prompt"

payload = { "sections": [
        {
            "content": "<string>",
            "fields": [
                {
                    "label": "Email",
                    "question": "What is the best email to send the quote to?",
                    "complete_when": "a valid email address is given"
                }
            ]
        }
    ] }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sections: [
      {
        content: '<string>',
        fields: [
          {
            label: 'Email',
            question: 'What is the best email to send the quote to?',
            complete_when: 'a valid email address is given'
          }
        ]
      }
    ]
  })
};

fetch('https://api.withallo.com/v2/api/numbers/{number}/agent/prompt', 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.withallo.com/v2/api/numbers/{number}/agent/prompt",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'sections' => [
        [
                'content' => '<string>',
                'fields' => [
                                [
                                                                'label' => 'Email',
                                                                'question' => 'What is the best email to send the quote to?',
                                                                'complete_when' => 'a valid email address is given'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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.withallo.com/v2/api/numbers/{number}/agent/prompt"

	payload := strings.NewReader("{\n  \"sections\": [\n    {\n      \"content\": \"<string>\",\n      \"fields\": [\n        {\n          \"label\": \"Email\",\n          \"question\": \"What is the best email to send the quote to?\",\n          \"complete_when\": \"a valid email address is given\"\n        }\n      ]\n    }\n  ]\n}")

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

	req.Header.Add("Authorization", "<api-key>")
	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.put("https://api.withallo.com/v2/api/numbers/{number}/agent/prompt")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sections\": [\n    {\n      \"content\": \"<string>\",\n      \"fields\": [\n        {\n          \"label\": \"Email\",\n          \"question\": \"What is the best email to send the quote to?\",\n          \"complete_when\": \"a valid email address is given\"\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withallo.com/v2/api/numbers/{number}/agent/prompt")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sections\": [\n    {\n      \"content\": \"<string>\",\n      \"fields\": [\n        {\n          \"label\": \"Email\",\n          \"question\": \"What is the best email to send the quote to?\",\n          \"complete_when\": \"a valid email address is given\"\n        }\n      ]\n    }\n  ]\n}"

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

{
  "data": {
    "sections": [
      {
        "title": "Objective",
        "content": "Book a visit with the caller.",
        "fields": [
          {
            "label": "Email",
            "question": "What is the best email to send the quote to?",
            "complete_when": "a valid email address is given"
          }
        ]
      }
    ],
    "custom_prompt": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

PUT

api

numbers

{number}

agent

prompt

Set the AI receptionist prompt

curl --request PUT \
  --url https://api.withallo.com/v2/api/numbers/{number}/agent/prompt \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "sections": [
    {
      "content": "<string>",
      "fields": [
        {
          "label": "Email",
          "question": "What is the best email to send the quote to?",
          "complete_when": "a valid email address is given"
        }
      ]
    }
  ]
}
'

import requests

url = "https://api.withallo.com/v2/api/numbers/{number}/agent/prompt"

payload = { "sections": [
        {
            "content": "<string>",
            "fields": [
                {
                    "label": "Email",
                    "question": "What is the best email to send the quote to?",
                    "complete_when": "a valid email address is given"
                }
            ]
        }
    ] }
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    sections: [
      {
        content: '<string>',
        fields: [
          {
            label: 'Email',
            question: 'What is the best email to send the quote to?',
            complete_when: 'a valid email address is given'
          }
        ]
      }
    ]
  })
};

fetch('https://api.withallo.com/v2/api/numbers/{number}/agent/prompt', 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.withallo.com/v2/api/numbers/{number}/agent/prompt",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'sections' => [
        [
                'content' => '<string>',
                'fields' => [
                                [
                                                                'label' => 'Email',
                                                                'question' => 'What is the best email to send the quote to?',
                                                                'complete_when' => 'a valid email address is given'
                                ]
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "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.withallo.com/v2/api/numbers/{number}/agent/prompt"

	payload := strings.NewReader("{\n  \"sections\": [\n    {\n      \"content\": \"<string>\",\n      \"fields\": [\n        {\n          \"label\": \"Email\",\n          \"question\": \"What is the best email to send the quote to?\",\n          \"complete_when\": \"a valid email address is given\"\n        }\n      ]\n    }\n  ]\n}")

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

	req.Header.Add("Authorization", "<api-key>")
	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.put("https://api.withallo.com/v2/api/numbers/{number}/agent/prompt")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"sections\": [\n    {\n      \"content\": \"<string>\",\n      \"fields\": [\n        {\n          \"label\": \"Email\",\n          \"question\": \"What is the best email to send the quote to?\",\n          \"complete_when\": \"a valid email address is given\"\n        }\n      ]\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.withallo.com/v2/api/numbers/{number}/agent/prompt")

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

request = Net::HTTP::Put.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"sections\": [\n    {\n      \"content\": \"<string>\",\n      \"fields\": [\n        {\n          \"label\": \"Email\",\n          \"question\": \"What is the best email to send the quote to?\",\n          \"complete_when\": \"a valid email address is given\"\n        }\n      ]\n    }\n  ]\n}"

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

{
  "data": {
    "sections": [
      {
        "title": "Objective",
        "content": "Book a visit with the caller.",
        "fields": [
          {
            "label": "Email",
            "question": "What is the best email to send the quote to?",
            "complete_when": "a valid email address is given"
          }
        ]
      }
    ],
    "custom_prompt": "<string>"
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

{
  "error": {
    "type": "<string>",
    "code": "<string>",
    "message": "<string>",
    "retryable": true,
    "request_id": "<string>",
    "retry_after_seconds": 123
  }
}

Required scope: AGENTS_WRITE

Behavior

Replaces the receptionist’s prompt: what it is trying to achieve, who it is, and how it handles the call. A prompt is only valid whole, and every write re-renders what the receptionist answers with, so read the current sections with Get configuration and send them all back, including the ones you are not changing. The response echoes the prompt with a title derived server-side from each section key.

Sections

Section	Required	Body
`objective`	Yes	`content`
`personality`	Yes	`content`
`behaviors`	Yes	`content`
`prohibited`	No	`content`
`required_fields`	No	`fields`
`objective_completion`	No	`content`

required_fields is the one section that carries fields instead of content, one entry per piece of information the receptionist has to collect. Every other section carries non-blank content and no fields. Each section may appear at most once, and content holds up to 3000 characters. The three required sections are the minimum the API enforces, not the prompt a business needs. A receptionist with no prohibited section was never told what it must not say.

What belongs elsewhere

Facts about the business go in knowledge on Update configuration, not here. Prices, opening hours, policies and FAQs change often, and the receptionist looks them up rather than reciting them from the prompt. The greeting and the closing message are their own fields too. Allo already handles greeting, closing, language switching, contact confirmation, transfer and booking mechanics, so restating them in the prompt makes the call worse, not better.

Errors

400 PROMPT_SECTIONS_REQUIRED: sections was missing or empty. It replaces the whole prompt, so it has to carry every section you want to keep.
400 INVALID_AGENT_PROMPT_SECTION: an unknown section key. The allowed ones are listed in the message.
400 DUPLICATE_AGENT_PROMPT_SECTION: a section appears more than once.
400 INVALID_AGENT_PROMPT_SECTION_BODY: a section carries the wrong body, for example fields on objective.
400 MISSING_AGENT_PROMPT_SECTION: one of objective, personality or behaviors is missing or blank.
400 AGENT_PROMPT_SECTION_TOO_LONG: a section’s content is over 3000 characters.
400 AGENT_PROMPT_TOO_LONG: the prompt rendered from all sections is over 25000 characters.
404 PHONE_NUMBER_NOT_FOUND: the number is not one you have access to.

Authorizations

Authorization

string

header

required

Path Parameters

number

string

required

Allo phone number in E.164 format

Example:

"+14155551234"

Body

application/json

Replaces the whole prompt. objective, personality and behaviors are required; each section may appear once; a content section holds at most 3000 characters.

sections

object[]

required

Show child attributes

Response

The prompt after the write, with server-derived titles

data

object

The receptionist's prompt. Exactly one of the two keys is present: sections for a prompt written in the section format, custom_prompt for an older line whose prompt was written as freeform text. custom_prompt is the render of the sections, so it is never reported alongside them.

Show child attributes

API

Webhooks

Conversations

People

Companies

Deals

Notes

Threads

Phone Numbers

AI Receptionist

Tags

Summary Templates

Users

SMS

Analytics

Power Dialer

Partner

Behavior

Sections

What belongs elsewhere

Errors

Authorizations

Path Parameters

Body

Response

​Behavior

​Sections

​What belongs elsewhere

​Errors

Authorizations

Path Parameters

Body

Response

Behavior

Sections

What belongs elsewhere

Errors