> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an agent action

> Voice agents: start_test_call (a browser test call), hangup_test_call (needs call_id), meeting_types (needs calendar_id) or test_tool (needs tool_id). Chat agents: start_chat (the agent writes first to one number or lead), start_many (up to 25 chats), replay a conversation, test with a short chat, suggest_rules, rotate_trigger, approve or reject a pending action, or test_custom_action. Starting chats sends real messages. Requires write access. This operation can change workspace data or trigger an external side effect; review the request before sending it and do not retry blindly after a timeout.



## OpenAPI

````yaml /openapi.json post /api/v1/public/agents/{agent_id}/actions
openapi: 3.1.0
info:
  description: >-
    Customer-facing API for managing outreach, leads, conversations, voice
    agents, knowledge bases, analytics, and webhooks.
  title: Sendora Public API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.sendora.ai
security: []
tags:
  - description: Leads, lead lists, importing, enriching and finding new prospects.
    name: Leads
  - description: Build, run and measure outreach, and enroll leads.
    name: Campaigns
  - description: Read and send messages, and manage who must not be contacted.
    name: Conversations
  - description: >-
      Voice and chat agents, their tools, knowledge bases, voices and website
      widgets.
    name: Agents
  - description: >-
      Start calls, and manage phone numbers, SMS registration, sending accounts
      and email domains.
    name: Calls and numbers
  - description: Webhooks, jobs, analytics and the Copilot assistant.
    name: Platform
  - description: Manage client workspaces, plans and branding.
    name: Agency
paths:
  /api/v1/public/agents/{agent_id}/actions:
    post:
      tags:
        - Agents
      summary: Run an agent action
      description: >-
        Voice agents: start_test_call (a browser test call), hangup_test_call
        (needs call_id), meeting_types (needs calendar_id) or test_tool (needs
        tool_id). Chat agents: start_chat (the agent writes first to one number
        or lead), start_many (up to 25 chats), replay a conversation, test with
        a short chat, suggest_rules, rotate_trigger, approve or reject a pending
        action, or test_custom_action. Starting chats sends real messages.
        Requires write access. This operation can change workspace data or
        trigger an external side effect; review the request before sending it
        and do not retry blindly after a timeout.
      operationId: agent_action_api_v1_public_agents__agent_id__actions_post
      parameters:
        - description: >-
            The voice agent's id: the `id` from List or get agents. It is also
            the last part of that page's address in the app.
          in: path
          name: agent_id
          required: true
          schema:
            title: Agent Id
            type: string
        - in: header
          name: X-API-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-Api-Key
        - in: header
          name: Authorization
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              discriminator:
                mapping:
                  approve: '#/components/schemas/ChatAction'
                  hangup_test_call: '#/components/schemas/VoiceAction'
                  reject: '#/components/schemas/ChatAction'
                  replay: '#/components/schemas/ChatAction'
                  rotate_trigger: '#/components/schemas/ChatAction'
                  start_chat: '#/components/schemas/ChatAction'
                  start_many: '#/components/schemas/ChatAction'
                  start_test_call: '#/components/schemas/VoiceAction'
                  suggest_rules: '#/components/schemas/ChatAction'
                  test: '#/components/schemas/ChatAction'
                  test_custom_action: '#/components/schemas/ChatAction'
                  test_tool: '#/components/schemas/VoiceAction'
                propertyName: action
              oneOf:
                - $ref: '#/components/schemas/VoiceAction'
                - $ref: '#/components/schemas/ChatAction'
              title: Body
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                title: >-
                  Response Agent Action Api V1 Public Agents  Agent Id  Actions
                  Post
          description: Successful Response
        '401':
          description: The X-API-Key header is missing, invalid, expired, or revoked.
        '402':
          description: >-
            The workspace is suspended for billing, or the request would exceed
            a plan or usage limit.
        '403':
          description: >-
            The key is valid but lacks the required scope, or the workspace has
            no active plan, lacks the entitlement, or has this feature turned
            off or view-only.
        '404':
          description: >-
            The resource does not exist or is not owned by the authenticated
            workspace.
        '410':
          description: The workspace behind this key has been deleted.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
        '500':
          description: >-
            An unexpected Sendora error occurred. Retry only if the operation is
            safe to repeat.
        '503':
          description: >-
            An entitlement or billing check is temporarily unavailable. Retry
            after the Retry-After interval.
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - label: cURL
          lang: bash
          source: >-
            curl -X POST
            'https://api.sendora.ai/api/v1/public/agents/YOUR_ID/actions' -H
            "X-API-Key: $SENDORA_API_KEY" -H "Content-Type: application/json" \
              -d '{"action":"start_test_call"}'
        - label: Python
          lang: python
          source: >-
            import requests


            url = 'https://api.sendora.ai/api/v1/public/agents/YOUR_ID/actions'

            headers = {'X-API-Key': '$SENDORA_API_KEY'}

            response = requests.post(url, headers=headers, json={'action':
            'start_test_call'})

            response.raise_for_status()

            print(response.json())
        - label: JavaScript
          lang: javascript
          source: >-
            const response = await
            fetch("https://api.sendora.ai/api/v1/public/agents/YOUR_ID/actions",
            {
              method: "POST",
              headers: { 'X-API-Key': process.env.SENDORA_API_KEY, 'Content-Type': 'application/json' },
              body: JSON.stringify({"action": "start_test_call"}),
            });

            if (!response.ok) throw new Error(await response.text());

            console.log(await response.json());
        - label: Go
          lang: go
          source: >-
            req, err := http.NewRequest("POST",
            "https://api.sendora.ai/api/v1/public/agents/YOUR_ID/actions",
            bytes.NewBufferString(`{"action": "start_test_call"}`))

            if err != nil { log.Fatal(err) }

            req.Header.Set("X-API-Key", os.Getenv("SENDORA_API_KEY"))

            req.Header.Set("Content-Type", "application/json")

            resp, err := http.DefaultClient.Do(req)

            if err != nil { log.Fatal(err) }

            defer resp.Body.Close()
components:
  schemas:
    ChatAction:
      properties:
        action:
          description: Action returned by the Sendora API.
          enum:
            - start_chat
            - replay
            - start_many
            - test
            - suggest_rules
            - rotate_trigger
            - approve
            - reject
            - test_custom_action
          title: Action
          type: string
        approval_id:
          anyOf:
            - type: string
            - type: 'null'
          description: 'approve and reject: a pending approval''s id'
          title: Approval Id
        channel:
          anyOf:
            - enum:
                - sms
                - whatsapp
                - email
              type: string
            - type: 'null'
          description: start_chat, start_many and test
          title: Channel
        conversation_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The conversation this message belongs to. It identifies the thread
            inside this workspace's inbox only.
          title: Conversation Id
        lead_id:
          anyOf:
            - maxLength: 64
              type: string
            - type: 'null'
          description: 'A lead''s id: the `id` from List or get leads.'
          title: Lead Id
        messages:
          anyOf:
            - items:
                additionalProperties:
                  type: string
                type: object
              type: array
            - type: 'null'
          description: 'test: a short chat, each {role, content}'
          title: Messages
        opening:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          description: 'start_chat and start_many: the first message'
          title: Opening
        phone:
          anyOf:
            - maxLength: 32
              type: string
            - type: 'null'
          description: >-
            start_chat: the number to message, with country code (or give
            lead_id)
          title: Phone
        phones:
          anyOf:
            - items:
                type: string
              maxItems: 25
              type: array
            - type: 'null'
          description: 'start_many: up to 25 numbers'
          title: Phones
        text:
          anyOf:
            - maxLength: 1000
              type: string
            - type: 'null'
          description: 'suggest_rules: what the agent should do'
          title: Text
        tool_id:
          anyOf:
            - type: string
            - type: 'null'
          description: 'test_custom_action: the action''s id'
          title: Tool Id
      required:
        - action
      title: ChatAction
      type: object
    VoiceAction:
      properties:
        action:
          description: Action returned by the Sendora API.
          enum:
            - start_test_call
            - hangup_test_call
            - test_tool
          title: Action
          type: string
        call_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The call's tracking id. Pass it to List or get calls once the call
            has ended.
          title: Call Id
        template_context:
          description: 'start_test_call: values for the call''s variables'
          title: Template Context
          type: object
        text_only:
          default: false
          description: 'start_test_call: a typed test where the agent answers in text'
          title: Text Only
          type: boolean
        tool_id:
          anyOf:
            - type: string
            - type: 'null'
          description: 'test_tool: the tool''s id'
          title: Tool Id
      required:
        - action
      title: VoiceAction
      type: object
    HTTPValidationError:
      properties:
        detail:
          description: Detail returned by the Sendora API.
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      required: []
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        loc:
          description: Loc returned by the Sendora API.
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          description: Msg returned by the Sendora API.
          title: Message
          type: string
        type:
          description: Type returned by the Sendora API.
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Customer API key created in the Sendora dashboard.
      in: header
      name: X-API-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.