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

# Create a macro

> Create an org-wide macro (saved reply) with an HTML body, {{variable}} placeholders, up to 3 tappable options, and an optional opt-out of suggestions.

Write the body in any language. If translation languages are chosen (see [Update macro settings](./update-settings)), the new macro is translated into each of them in the background.

```json theme={"dark"}
{
  "category": "Billing",
  "title": "Refund status",
  "content": "<p>Hi {{contact.full_name}}, your refund is on its way and should arrive within 5 business days.</p>",
  "exclude_from_suggestions": false
}
```

Look up valid `{{variable}}` names with [List macro variables](./variables). Attachments cannot be set through the API.


## OpenAPI

````yaml post /macros
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /macros:
    post:
      summary: Create a macro
      description: >-
        Create a new saved-reply macro. Use {{variable}} syntax in content to
        reference system or custom variables. Attachments are dashboard-authored
        and cannot be set via the public API.
      operationId: createMacro
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMacroInput'
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedReplyDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    CreateMacroInput:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/CreateMacroInputInput'
      type: object
      properties:
        category:
          type: string
        title:
          type: string
        content:
          type: string
          maxLength: 20000
          description: >-
            Macro body as HTML, limited to what every channel can carry: <p>,
            <br>, <strong>, <em>, <s>, <a href>, <ul>/<ol start>/<li> and inline
            images as `<img src="…">` pointing at a file uploaded for this
            organization. Other markup is dropped (its text is kept); escape
            literal < and & as HTML entities, and use <br> or <p> for line
            breaks. Reference variables with {{variable}} syntax.
        options:
          description: >-
            Up to 3 options the customer can tap instead of typing, sent with
            the macro on channels that show them. Each `label` is up to 20
            characters. `type` is `text` (the tap reaches the session as the
            customer's reply) or `workflow` (the tap runs the macro's Macro
            Option Clicked workflows and the AI doesn't reply). This is the full
            list: on update, pass an existing option's `id` to keep it
            (workflows branching on that id keep working); options left out are
            removed, `[]` removes all, and omitting the field leaves them
            untouched. A macro with options needs body text.
          maxItems: 3
          type: array
          items:
            $ref: '#/components/schemas/MacroOptionInputDto'
        exclude_from_suggestions:
          description: >-
            When true, this macro is never suggested to agents. They can still
            search for it and use it. Defaults to false.
          type: boolean
      required:
        - category
        - title
        - content
    SavedReplyDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/SavedReplyDto'
      type: object
      properties:
        id:
          type: string
        org_id:
          type: string
        category:
          type: string
        title:
          type: string
        content:
          type: string
          description: Macro body as channel-safe HTML, with {{variable}} references.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/MacroAttachmentDto'
        options:
          type: array
          items:
            $ref: '#/components/schemas/MessageOptionDto'
        user_id:
          anyOf:
            - type: number
            - type: 'null'
        overrides_saved_reply_id:
          anyOf:
            - type: string
            - type: 'null'
        exclude_from_suggestions:
          type: boolean
        source_language:
          anyOf:
            - type: string
            - type: 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - org_id
        - category
        - title
        - content
        - attachments
        - options
        - user_id
        - overrides_saved_reply_id
        - exclude_from_suggestions
        - source_language
        - created_at
        - updated_at
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    MacroOptionInputDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MacroOptionInputDtoInput'
      type: object
      properties:
        id:
          type: string
        label:
          type: string
          minLength: 1
          maxLength: 20
        type:
          $ref: '#/components/schemas/MessageOptionType'
      required:
        - label
        - type
    MacroAttachmentDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MacroAttachmentDto'
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        size:
          type: number
        type:
          type: string
        url:
          type: string
      required:
        - id
        - name
        - size
        - type
        - url
      additionalProperties: false
    MessageOptionDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MessageOptionDto'
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        type:
          $ref: '#/components/schemas/MessageOptionType'
      required:
        - id
        - label
        - type
      additionalProperties: false
    MessageOptionType:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/MessageOptionType'
      type: string
      enum:
        - text
        - workflow
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

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