Macros | Bird API Docs

List Macros

get

Retrieve list of macros.

Authorizations

Path parameters

workspaceIdstringRequired

Query parameters

limitinteger · min: 1 · max: 100Optional

Limits the number of results to return

Default: 10

pageTokenstring · max: 8000Optional

Pagination token that keeps of track of the current position in the list

reversebooleanOptional

Order in which to retrieve the results

Default: false

sortstring · enumOptional

The field by which to sort macros.

Default: createdAtPossible values:

qstringOptional

A full-text search parameter that searches for macros by name, response body, and/or tag name.

languagesstring · locale-bcp47[]Optional

Filter macros by language. Multiple languages are combined with a logical OR.

tagIdsstring · uuid[]Optional

Filter macros by tag IDs. Multiple tag IDs are combined with a logical AND.

Responses

200

OK

application/json

422

Invalid request

application/json

get

GET /workspaces/{workspaceId}/macros HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "response": {
        "type": "text",
        "text": {
          "text": "text",
          "attachments": [
            {
              "mediaUrl": "https://example.com",
              "filename": "text",
              "inline": true,
              "contentId": "text"
            }
          ],
          "actions": [
            {
              "type": "link",
              "link": {
                "text": "text",
                "url": "text"
              }
            }
          ],
          "metadata": {
            "subject": "text",
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "whatsapp": {
              "previewUrl": true
            },
            "line": {
              "emoji": {
                "items": [
                  {
                    "index": 1,
                    "productId": "text",
                    "emojiId": "text",
                    "length": 1
                  }
                ]
              }
            },
            "telegram": {
              "parseMode": "Markdown"
            }
          }
        }
      },
      "language": "text",
      "usageCount": 1,
      "tags": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "description": "text",
          "status": "draft",
          "category": {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "name": "text",
            "description": "text",
            "emoji": "text",
            "createdAt": "text",
            "updatedAt": "text"
          },
          "agentCount": 1,
          "itemCount": 1,
          "macroCount": 1,
          "createdAt": "text",
          "updatedAt": "text",
          "deletedAt": "text",
          "lastUsed": {
            "addedToItemAt": "text",
            "addedToItemId": "123e4567-e89b-12d3-a456-426614174000",
            "removedFromItemAt": "text",
            "removedFromItemId": "123e4567-e89b-12d3-a456-426614174000"
          },
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "createdAt": "2025-07-03T02:16:05.851Z",
      "updatedAt": "2025-07-03T02:16:05.851Z",
      "actions": [
        {
          "type": "text",
          "params": {
            "ANY_ADDITIONAL_PROPERTY": "anything"
          },
          "source": {
            "macroId": "123e4567-e89b-12d3-a456-426614174000",
            "actionId": "123e4567-e89b-12d3-a456-426614174000"
          },
          "outcome": "OK",
          "cause": "text"
        }
      ]
    }
  ],
  "nextPageToken": "text"
}

Create Macro

post

Add a new macro to a workspace.

Authorizations

Path parameters

workspaceIdstringRequired

Body

namestring · min: 1 · max: 255Required

The user-defined display name of the macro.

responseall of | nullableOptional

and

one ofOptional

or

languagestring · locale-bcp47Optional

The optional user-defined language of the macro.

tagIdsstring · uuid[] · max: 25Optional

The list of tag IDs to associate with the macro.

Responses

201

Successfully created

application/json

404

Workspace not found

application/json

409

Macro already exists

application/json

422

Invalid request

application/json

post

POST /workspaces/{workspaceId}/macros HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 734

{
  "name": "text",
  "response": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "language": "text",
  "tagIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "actions": [
    {
      "type": "text",
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": {
        "macroId": "123e4567-e89b-12d3-a456-426614174000",
        "actionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "outcome": "OK",
      "cause": "text"
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "response": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text",
                "length": 1
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "language": "text",
  "usageCount": 1,
  "tags": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "status": "draft",
      "category": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "emoji": "text",
        "createdAt": "text",
        "updatedAt": "text"
      },
      "agentCount": 1,
      "itemCount": 1,
      "macroCount": 1,
      "createdAt": "text",
      "updatedAt": "text",
      "deletedAt": "text",
      "lastUsed": {
        "addedToItemAt": "text",
        "addedToItemId": "123e4567-e89b-12d3-a456-426614174000",
        "removedFromItemAt": "text",
        "removedFromItemId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "createdAt": "2025-07-03T02:16:05.851Z",
  "updatedAt": "2025-07-03T02:16:05.851Z",
  "actions": [
    {
      "type": "text",
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": {
        "macroId": "123e4567-e89b-12d3-a456-426614174000",
        "actionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "outcome": "OK",
      "cause": "text"
    }
  ]
}

Get Macro

get

Retrieve information about a specific macro.

Authorizations

Path parameters

workspaceIdstringRequired

macroIdstring · uuidRequired

Macro UUID

Responses

200

ok

application/json

404

Workspace or macro not found

application/json

get

GET /workspaces/{workspaceId}/macros/{macroId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "response": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text",
                "length": 1
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "language": "text",
  "usageCount": 1,
  "tags": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "status": "draft",
      "category": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "emoji": "text",
        "createdAt": "text",
        "updatedAt": "text"
      },
      "agentCount": 1,
      "itemCount": 1,
      "macroCount": 1,
      "createdAt": "text",
      "updatedAt": "text",
      "deletedAt": "text",
      "lastUsed": {
        "addedToItemAt": "text",
        "addedToItemId": "123e4567-e89b-12d3-a456-426614174000",
        "removedFromItemAt": "text",
        "removedFromItemId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "createdAt": "2025-07-03T02:16:05.851Z",
  "updatedAt": "2025-07-03T02:16:05.851Z",
  "actions": [
    {
      "type": "text",
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": {
        "macroId": "123e4567-e89b-12d3-a456-426614174000",
        "actionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "outcome": "OK",
      "cause": "text"
    }
  ]
}

Update Macro

patch

Modify fields of a specific macro.

Authorizations

Path parameters

workspaceIdstringRequired

macroIdstring · uuidRequired

Macro UUID

Body

Specified properties will replace the existing values of those properties in the macro. An explicit null value will remove the corresponding property, where supported.

namestring | nullableOptional

The user-defined display name of the macro.

responseall of | nullableOptional

and

one ofOptional

or

languagestring · locale-bcp47 | nullableOptional

The optional user-defined language of the macro.

tagIdsstring · uuid[] · max: 25Optional

The list of tag IDs to associate with the macro. An empty list will remove all tags.

Responses

200

Successfully updated

application/json

404

Macro or workspace not found

application/json

422

Invalid request

application/json

patch

PATCH /workspaces/{workspaceId}/macros/{macroId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 734

{
  "name": "text",
  "response": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "language": "text",
  "tagIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "actions": [
    {
      "type": "text",
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": {
        "macroId": "123e4567-e89b-12d3-a456-426614174000",
        "actionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "outcome": "OK",
      "cause": "text"
    }
  ]
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "text",
  "response": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text",
                "length": 1
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "language": "text",
  "usageCount": 1,
  "tags": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "description": "text",
      "status": "draft",
      "category": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "description": "text",
        "emoji": "text",
        "createdAt": "text",
        "updatedAt": "text"
      },
      "agentCount": 1,
      "itemCount": 1,
      "macroCount": 1,
      "createdAt": "text",
      "updatedAt": "text",
      "deletedAt": "text",
      "lastUsed": {
        "addedToItemAt": "text",
        "addedToItemId": "123e4567-e89b-12d3-a456-426614174000",
        "removedFromItemAt": "text",
        "removedFromItemId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "createdAt": "2025-07-03T02:16:05.851Z",
  "updatedAt": "2025-07-03T02:16:05.851Z",
  "actions": [
    {
      "type": "text",
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": {
        "macroId": "123e4567-e89b-12d3-a456-426614174000",
        "actionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "outcome": "OK",
      "cause": "text"
    }
  ]
}

Delete Macro

delete

Remove a specific macro.

Authorizations

Path parameters

workspaceIdstringRequired

macroIdstring · uuidRequired

Macro UUID

Responses

204

Successfully deleted

404

Macro or workspace not found

application/json

delete

DELETE /workspaces/{workspaceId}/macros/{macroId} HTTP/1.1
Host: 
Authorization: Bearer jwt
Accept: */*

No content

Get Macro with variable substitutions applied.

post

Retrieves the macro with variable substitutions applied to the response body.

Authorizations

Path parameters

workspaceIdstringRequired

macroIdstring · uuidRequired

Macro UUID

Body

Specifies the parameters for previewing a macro.

itemIdstring · uuidOptional

The ID of the feed item to source variables from. May be omitted where no feed item exists.

contactIdstring · uuidOptionalDeprecated

The ID of the contact to source variables from. If not provided, the macro will attempt to find a contact from the feed item.

contactone ofOptional

or

Responses

200

ok

application/json

404

Workspace, macro, or substitution source not found

application/json

422

Invalid request

application/json

post

POST /workspaces/{workspaceId}/macros/{macroId}/preview HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 321

{
  "itemId": "123e4567-e89b-12d3-a456-426614174000",
  "contact": {
    "id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "actions": [
    {
      "type": "text",
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": {
        "macroId": "123e4567-e89b-12d3-a456-426614174000",
        "actionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "outcome": "OK",
      "cause": "text"
    }
  ]
}

{
  "response": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text",
                "length": 1
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        }
      }
    }
  },
  "actions": [
    {
      "type": "text",
      "params": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "source": {
        "macroId": "123e4567-e89b-12d3-a456-426614174000",
        "actionId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "outcome": "OK",
      "cause": "text"
    }
  ]
}