Edit agent

Updates and publishes an existing agent. Only the fields you include are changed; everything else is left untouched. All fields are optional, so you can send partial updates.

Authentication

AuthorizationBearer

Authenticate server-side requests with a Fonema API key. Create one in the API keys section of the Dashboard and send it in the Authorization header as Bearer <token>. Keep keys out of client-side code and public repositories.

Path parameters

slugstringRequired

Unique slug of the agent to update.

Body

Top-level parameters

namestringOptional

Agent name.

greetingstringOptional

Opening message said when the call starts.

promptstringOptional

System prompt that defines the agent behavior.

textPromptstringOptional

Prompt used for text/chat conversations.

farewellstringOptional

Closing message said at the end of the call.

voiceIdstringOptional

Voice identifier for the agent. Get available values from List voices.

outputVariablesarrayOptional

Variables to capture during the call (same shape as in Create agent).

recallLogicobjectOptional

Retry configuration for calls that are not answered. See recallLogic.

numberOfAttemptintegerOptional

Total number of call attempts (first call + retries).

allowReturnCallbooleanOptional

Whether the agent allows return calls.

localizationsobjectOptional

Localization settings.

workingHoursobjectOptional

Hours when the agent can place calls. See workingHours.

dtmfbooleanOptional

Whether the agent can press keypad tones (DTMF) during the call, e.g. to navigate phone menus (IVR).

transferCallDestinationsarrayOptional

Phone numbers the agent can transfer the call to. An empty array disables transfers. See transferCallDestinations.

endOfCallWebhookstringOptional

URL notified when a call ends.

endOfSessionWebhookstringOptional

URL notified when a session ends.

callUpdatesWebhookstringOptional

URL notified on call status updates.

knowledgeBaseFilesinteger[]Optional

IDs of knowledge base files to attach.

toolsarrayOptional

Tools/skills available to the agent. See below.

configobjectOptional

Alternative way to send configuration values. See below.

tools items

tools[].idinteger

ID of an existing tool (omit to create a new one).

tools[].namestring

Tool name. Falls back to content.functionName if omitted.

tools[].typestring

Tool type (e.g. API_CALL).

tools[].descriptionstring

What the tool does.

tools[].variablesarray

Input variables for the tool.

tools[].contentobject

Tool implementation details (function name, URL, auth, etc.).

config object

config accepts the same configuration as several top-level fields. You can send values either at the top level or inside config — top-level fields take precedence when both are present. Supported keys:

transcriberLanguage, endOfCallMessage, silenceTimeoutSeconds, silenceMessages, maxDurationSeconds, voice, captureDataVariables, endOfCallWebhook, endOfSessionWebhook, callUpdatesWebhook, allowReturnCall, workingHours, dtmf, transferCallDestinations, localizations.

The keys that only exist inside config are:

config.transcriberLanguagestring

Language the agent listens in. One of es, es-419 (Latin American Spanish), en, pt, pt-BR, ro.

config.endOfCallMessagestring

Same as the top-level farewell.

config.silenceTimeoutSecondsnumber

Seconds of silence from the caller before the call is ended.

config.silenceMessagesstring[]

Phrases the agent says when the caller stays silent (one is picked at random) before the silence timeout ends the call. Only used when silenceTimeoutSeconds is set. Sending this field replaces the whole list; send [] to clear it.

config.maxDurationSecondsnumber

Maximum call duration, in seconds.

config.voiceobject

Fine-tuning of the agent voice. See config.voice.

config.captureDataVariablesarray

Same as the top-level outputVariables.

config.voice object

config.voice.stabilitynumber0 – 1

Higher values sound more stable and consistent; lower values sound more expressive and variable.

config.voice.similarityBoostnumber0 – 1

How closely the generated audio matches the original voice (clarity).

config.voice.speednumber0.7 – 1.2

Speaking speed. 1 is normal speed.

Only the keys you send are changed; the rest keep their current value.

recallLogic object

Controls automatic retries when a call is not answered (no answer, busy, voicemail, etc.).

recallLogic.allowRetryboolean

Enables automatic retries.

recallLogic.triesarray

One item per retry, in order. Each item is { "waitMinutes": number }: minutes to wait after the previous unanswered attempt before calling again. The number of items is the number of retries.

recallLogic.timeZonestringDefaults to America/Mexico_City

IANA time zone used to schedule retries (e.g. America/Mexico_City). Defaults to America/Mexico_City.

recallLogic.scheduleTypestring

SAME_AS_WORKING to retry only within workingHours, or CUSTOM to use availability.

recallLogic.availabilityobject

Retry hours when scheduleType is CUSTOM. Same shape as workingHours.availability.

note

tries, availability and scheduleType are replaced as a whole every time you send recallLogic, so always send the complete list of tries.

Example: retry twice, 30 and 120 minutes after an unanswered call, for a total of 3 attempts:

{
  "numberOfAttempt": 3,
  "recallLogic": {
    "allowRetry": true,
    "timeZone": "America/Mexico_City",
    "scheduleType": "SAME_AS_WORKING",
    "tries": [{ "waitMinutes": 30 }, { "waitMinutes": 120 }]
  }
}

workingHours object

workingHours.typestring

ALL_DAY (no restriction) or CUSTOM.

workingHours.availabilityobject

Required when type is CUSTOM. Keys are days (monday … sunday); each value is a list of { "start": "HH:mm", "end": "HH:mm" } windows. Days that are missing or empty are unavailable.

{
  "workingHours": {
    "type": "CUSTOM",
    "availability": {
      "monday": [{ "start": "09:00", "end": "18:00" }],
      "tuesday": [{ "start": "09:00", "end": "14:00" }, { "start": "16:00", "end": "19:00" }]
    }
  }
}

transferCallDestinations items

Each destination is a phone number the agent can transfer the call to. Send an empty array to disable transfers.

transferCallDestinations[].numberstringRequired

Destination phone number in E.164 format (e.g. +525512345678).

transferCallDestinations[].messagestringOptional

Message the agent says to the caller before transferring.

transferCallDestinations[].extensionstringOptional

Extension to dial after the call connects.

transferCallDestinations[].descriptionstringOptional

When the agent should transfer to this number. The agent uses it to choose the right destination.

{
  "transferCallDestinations": [
    {
      "number": "+525512345678",
      "message": "Let me transfer you to an advisor, one moment please.",
      "description": "Transfer when the customer asks to speak with a human advisor."
    }
  ]
}

Response

Returns the full, updated agent — the same structure as Get agent.

Errors

400

Invalid request body.

403

Agent not found or not accessible by this API key.

POST/v1/agents/:slug/publish

$curl -X POST "https://api.fonema.ai/v1/agents/sales-agent-ab12cd34/publish" \
>     -H "Authorization: Bearer YOUR_API_KEY" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "name": "API Test Agent",
>  "greeting": "Hello! Thanks for calling.",
>  "prompt": "You are a helpful sales assistant.",
>  "farewell": "Thank you for calling. Goodbye!",
>  "voiceId": "YOUR_VOICE_ID",
>  "allowReturnCall": true,
>  "numberOfAttempt": 3,
>  "outputVariables": [
>    {
>      "name": "customerName",
>      "description": "The caller'\''s full name",
>      "type": "string"
>    }
>  ],
>  "knowledgeBaseFiles": [],
>  "tools": [
>    {
>      "name": "lookup_order",
>      "type": "API_CALL",
>      "description": "Look up an order by ID",
>      "variables": [
>        {
>          "orderId": {
>            "type": "string",
>            "description": "The order ID provided by the caller"
>          }
>        }
>      ],
>      "content": {
>        "functionName": "lookup_order",
>        "parameters": [
>          "orderId"
>        ],
>        "url": "https://example.com/api/orders",
>        "authType": "Bearer",
>        "token": "your-token-here"
>      }
>    }
>  ],
>  "config": {
>    "transcriberLanguage": "es-419",
>    "silenceTimeoutSeconds": 30,
>    "silenceMessages": [
>      "Are you still there?",
>      "Hello, can you hear me?"
>    ],
>    "maxDurationSeconds": 600,
>    "endOfCallWebhook": "https://example.com/webhooks/end-of-call"
>  }
>}'