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

# Create Call Token

> Creates a call token: a single-use pass to start one web call on an agent, valid for 30 seconds (the call itself can last longer). Use it to start calls from a web page without putting a secret key in it: your server creates the token with a secret key (`sk_`) and hands it to the page, and the Hamsa web SDK starts the call with it (`Authorization: CallToken <token>`). With a public key (`pk_`), the web SDK creates the token itself.

A call token is also the only way to run a call on a specific version or environment: `versionRef` and `environmentId` sent directly when starting a call are refused with 403 `CallTokenRequired`. With neither, the call runs what prod serves; during an A/B test, the side is picked now (send `callerKey` to keep one person on the same side).

Who can create one: a secret key (`sk_`, from your server: a request with an `Origin` header is refused), a public key (`pk_`: always for its own environment, so it can't send `versionRef` or `environmentId`), or a signed-in dashboard member. Legacy API keys can't. Needs the `agents:call` permission; a key limited to some agents works only for those.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/voice-agents/call-token
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v1/voice-agents/call-token:
    post:
      summary: Create a call token
      description: >-
        Creates a call token: a single-use pass to start one web call on an
        agent, valid for 30 seconds (the call itself can last longer). Use it to
        start calls from a web page without putting a secret key in it: your
        server creates the token with a secret key (`sk_`) and hands it to the
        page, and the Hamsa web SDK starts the call with it (`Authorization:
        CallToken <token>`). With a public key (`pk_`), the web SDK creates the
        token itself.


        A call token is also the only way to run a call on a specific version or
        environment: `versionRef` and `environmentId` sent directly when
        starting a call are refused with 403 `CallTokenRequired`. With neither,
        the call runs what prod serves; during an A/B test, the side is picked
        now (send `callerKey` to keep one person on the same side).


        Who can create one: a secret key (`sk_`, from your server: a request
        with an `Origin` header is refused), a public key (`pk_`: always for its
        own environment, so it can't send `versionRef` or `environmentId`), or a
        signed-in dashboard member. Legacy API keys can't. Needs the
        `agents:call` permission; a key limited to some agents works only for
        those.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - voiceAgentId
              properties:
                voiceAgentId:
                  type: string
                  format: uuid
                  description: The agent to call.
                  example: d949f13f-40d2-4e48-ac86-b66633070603
                versionRef:
                  type: string
                  minLength: 1
                  maxLength: 100
                  description: >-
                    Optional. The version to run: a version ID, `draft` (your
                    own draft), or `draft:<draftId>` (a proposed draft; needs
                    the `agents:review_drafts` permission). Omit it to run what
                    the environment, or prod, serves. Not with a public key.
                  example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                environmentId:
                  type: string
                  format: uuid
                  description: >-
                    Optional. The environment whose version and values the call
                    uses. Not with a public key (it uses its own environment).
                  example: 5b9d1e7f-2c3a-4f8b-8d16-7e9f0a1b2c3d
                isChatOnly:
                  type: boolean
                  description: Optional. `true` for a text chat instead of a voice call.
                  example: false
                callerKey:
                  type: string
                  minLength: 1
                  maxLength: 200
                  description: >-
                    Optional. A stable ID for the person calling (for example
                    their user ID in your system), so their calls land on the
                    same side of an A/B test.
                  example: user-48213
            examples:
              live:
                summary: Run what prod serves
                value:
                  voiceAgentId: d949f13f-40d2-4e48-ac86-b66633070603
                  callerKey: user-48213
              environment:
                summary: Run an environment (secret key)
                value:
                  voiceAgentId: d949f13f-40d2-4e48-ac86-b66633070603
                  environmentId: 5b9d1e7f-2c3a-4f8b-8d16-7e9f0a1b2c3d
              version:
                summary: Run a version (secret key)
                value:
                  voiceAgentId: d949f13f-40d2-4e48-ac86-b66633070603
                  versionRef: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
                  environmentId: 5b9d1e7f-2c3a-4f8b-8d16-7e9f0a1b2c3d
              draft:
                summary: Test your draft, as chat
                value:
                  voiceAgentId: d949f13f-40d2-4e48-ac86-b66633070603
                  versionRef: draft
                  isChatOnly: true
      responses:
        '201':
          description: Token created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    type: object
                    properties:
                      callToken:
                        type: string
                        description: >-
                          The token. Starts with `ct_`. Works once, for 30
                          seconds.
                        example: ct_q3V8kz2Lx0n5Wb7Yc1Rf4Hj6Tm9Pa2Ds8Ge5Ku0Io3Nw
                      expiresAt:
                        type: string
                        format: date-time
                        description: When the token stops working.
                        example: '2026-10-31T12:00:30.000Z'
                      resolved:
                        $ref: '#/components/schemas/CallTokenResolvedTarget'
        '400':
          description: >-
            Invalid body (for example `versionRef: "latest"`, which is not
            supported).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: >-
            Not allowed: a legacy API key, share link or call token
            (`CallTokenSessionOnly`); a secret key sent from a browser
            (`SecretKeyInBrowser`); a public key that sent `versionRef` or
            `environmentId` (`PublicKeyFixedEnvironment`); a key limited to
            other agents (`KeyNotForAgent`); a public key with `allowedDomains`
            called from another origin; or no `agents:call` permission. A
            `projectId` in the query or the body that isn't the key's project
            gets "The projectId does not match the API key's project!".
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: >-
            Voice agent not found in this project, or the version or environment
            is not on this agent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '409':
          description: >-
            A `dev` or `staging` public key was used on an agent whose
            environment runs no version yet (`EnvironmentNotDeployed`). Deploy a
            version to it first.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '429':
          description: >-
            Too many call tokens for this public key (default 120 per minute;
            `ApiKeyRateLimited`). Wait for the `Retry-After` seconds.
          headers:
            Retry-After:
              description: Seconds to wait before trying again.
              schema:
                type: integer
                example: 12
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    CallTokenResolvedTarget:
      type: object
      description: What the call will run, fixed when the token is created.
      properties:
        versionId:
          type: string
          format: uuid
          nullable: true
          description: >-
            The version the call runs. With nothing pinned, the version prod
            serves.
          example: a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d
        versionNumber:
          type: integer
          nullable: true
          example: 4
        draftRevisionId:
          type: string
          format: uuid
          description: Present when the call runs a draft.
          example: 6e5d4c3b-2a1f-4e0d-9c8b-7a6f5e4d3c2b
        environmentId:
          type: string
          format: uuid
          nullable: true
          description: >-
            The environment whose values the call reads. `null` when none
            applies.
          example: 8c4e2a6b-3d9f-4a1c-9e27-0f1b2c3d4e5f
        splitApplies:
          type: boolean
          description: '`true` when prod''s A/B test picked this version for the call.'
          example: false
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

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