Skip to content
DashboardGet API key

Create agent

View .md
POST

Create an AI agent for a sender. Each sender can have at most one agent.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Path parameters

  • senderIdstringrequired

Body

application/json

  • namestringrequired
    Limitsmax length 100
  • providerstringrequired

    LLM provider for the AI agent.

    One ofopenaianthropicgooglemistralzavu
  • modelstringrequired
  • systemPromptstringrequired
    Limitsmax length 10000
  • apiKeystring

    API key for the LLM provider. Required unless provider is 'zavu'.

  • contextWindowMessagesinteger
    Default10
    Limitsmin 1 · max 50
  • includeContactMetadataboolean
    Defaulttrue
  • maxTokensinteger
    Limitsmin 1 · max 4096
  • temperaturenumber
    Limitsmin 0 · max 2
  • triggerOnChannelsstring[]
    Default["*"]
  • triggerOnMessageTypesstring[]
    Default["text"]
  • voiceobject

    Voice Agent configuration. Enable this to let the agent answer and place phone calls with Zavu's managed voice pipeline.

    17 properties
    • enabledbooleanrequired

      Whether the agent handles voice calls. When false, the sender's number is not answered by the voice agent and outbound calls are rejected.

    • greetingstring

      Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.

      Limitsmax length 1000
    • greetingsobject

      Greeting per language, keyed by language code. Used when the caller's language differs from the one greeting is written in.

      1 properties
      • {key}string
    • languagestring

      BCP-47 language code used for both speech recognition and speech synthesis (e.g. en, es, pt-BR). Auto-detected from the recipient when omitted.

    • modelstring

      Model that runs the conversation, co-located in the voice network for lowest latency. Independent of the model used for text messaging. Derived from the agent's text model when omitted.

    • sttProviderstring

      Speech-recognition provider. Uses the default when omitted.

    • sttModelstring

      Speech-recognition model. Uses the default when omitted.

    • ttsProviderstring

      Speech-synthesis provider. Uses the default when omitted.

    • ttsVoiceIdstring

      Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted.

    • voiceSpeednumber

      Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others.

      Default1
      Limitsmin 0.5 · max 1.5
    • interruptibleboolean

      Whether the caller can interrupt the agent while it is speaking (barge-in). When true, the agent stops talking as soon as the caller starts.

      Defaulttrue
    • maxCallDurationMinutesinteger

      Hard limit on call length in minutes. The call ends automatically when reached.

      Default15
      Limitsmin 1 · max 120
    • maxIdleSecondsinteger

      How long the agent waits during silence before ending the call.

      Default30
      Limitsmin 5 · max 300
    • recordCallsboolean

      Whether the call audio is recorded.

    • voicemailActionstring

      What the agent does when an answering machine or voicemail is detected on an outbound call.

      One ofhangupleave_message
      Defaulthangup
    • voicemailMessagestring

      Message spoken when voicemailAction is leave_message. Falls back to greeting when omitted.

      Limitsmax length 1000
    • transferPhoneNumberstring

      E.164 phone number the agent can transfer the call to. When set, the agent is given a transfer tool it can use to hand the call to a human.

Responses

201Agent created.
  • agentobjectrequired

    AI Agent configuration for a sender.

    18 properties
    • idstringrequired
    • senderIdstring

      The sender the agent was created on, its primary. Absent on an agent created with POST /v1/agents, which has no primary even after senders are connected to it. senderIds lists every sender the agent answers on.

    • namestringrequired
    • enabledbooleanrequired

      Whether the agent is active.

    • providerstringrequired

      LLM provider for the AI agent.

      One ofopenaianthropicgooglemistralzavu
    • modelstringrequired

      Model ID (e.g., gpt-4o-mini, claude-3-5-sonnet).

    • systemPromptstringrequired

      System prompt for the agent.

    • contextWindowMessagesinteger

      Number of previous messages to include as context.

      Default10
    • includeContactMetadataboolean

      Whether to include contact metadata in context.

      Defaulttrue
    • maxTokensintegernullable

      Maximum tokens for LLM response.

    • temperaturenumbernullable

      LLM temperature (0-2).

    • triggerOnChannelsstring[]

      Channels that trigger the agent.

    • triggerOnMessageTypesstring[]

      Message types that trigger the agent.

    • statsobject
      3 properties
      • totalInvocationsinteger
      • totalTokensUsedinteger
      • totalCostnumber

        Total cost in USD.

    • createdAtstring<date-time>required
    • updatedAtstring<date-time>required
    • voiceobject

      Voice Agent configuration. When present and enabled, the agent can answer inbound phone calls and place outbound calls with Zavu's managed voice pipeline.

      17 properties
      • enabledbooleanrequired

        Whether the agent handles voice calls. When false, the sender's number is not answered by the voice agent and outbound calls are rejected.

      • greetingstring

        Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.

        Limitsmax length 1000
      • greetingsobject

        Greeting per language, keyed by language code. Used when the caller's language differs from the one greeting is written in.

        1 properties
        • {key}string
      • languagestring

        BCP-47 language code used for both speech recognition and speech synthesis (e.g. en, es, pt-BR). Auto-detected from the recipient when omitted.

      • modelstring

        Model that runs the conversation, co-located in the voice network for lowest latency. Independent of the model used for text messaging. Derived from the agent's text model when omitted.

      • sttProviderstring

        Speech-recognition provider. Uses the default when omitted.

      • sttModelstring

        Speech-recognition model. Uses the default when omitted.

      • ttsProviderstring

        Speech-synthesis provider. Uses the default when omitted.

      • ttsVoiceIdstring

        Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted.

      • voiceSpeednumber

        Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others.

        Default1
        Limitsmin 0.5 · max 1.5
      • interruptibleboolean

        Whether the caller can interrupt the agent while it is speaking (barge-in). When true, the agent stops talking as soon as the caller starts.

        Defaulttrue
      • maxCallDurationMinutesinteger

        Hard limit on call length in minutes. The call ends automatically when reached.

        Default15
        Limitsmin 1 · max 120
      • maxIdleSecondsinteger

        How long the agent waits during silence before ending the call.

        Default30
        Limitsmin 5 · max 300
      • recordCallsboolean

        Whether the call audio is recorded.

      • voicemailActionstring

        What the agent does when an answering machine or voicemail is detected on an outbound call.

        One ofhangupleave_message
        Defaulthangup
      • voicemailMessagestring

        Message spoken when voicemailAction is leave_message. Falls back to greeting when omitted.

        Limitsmax length 1000
      • transferPhoneNumberstring

        E.164 phone number the agent can transfer the call to. When set, the agent is given a transfer tool it can use to hand the call to a human.

    • senderIdsstring[]

      Senders this agent answers on. An agent can serve several; senderId remains the primary one, for compatibility.

400Invalid request.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
404Sender not found.
  • codestringrequired
  • messagestringrequired
  • detailsobject
409`conflict`: the sender already answers with an agent, either one created on it or one connected to it with `POST /v1/agents/{agentId}/senders`. Update that agent instead, or disconnect it first.
  • codestringrequired
  • messagestringrequired
  • detailsobject