Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Automations

Endpoints related to DM automations, which send a direct message in response to a comment or message on a connected social account.

List DM automations

get

Lists the current user's DM automations, ordered by creation time (most recent first). Each automation includes run stats for the last 24 hours. Supports cursor-based pagination.

Authorizations
blotato-api-keystringRequired
Query parameters
limitinteger · min: 1 · max: 250Optional

Maximum number of DM automations to return. Defaults to 50.

Default: 50
cursorstringOptional

Opaque cursor returned by a previous call. Pass it to fetch the next page.

Responses
200

Default Response

application/json
cursorstringOptional

Cursor for the next page. Absent when there are no more DM automations.

get/v2/dm-automations
GET /v2/dm-automations HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "accountId": "text",
      "buttons": [
        {
          "title": "text",
          "type": "url",
          "url": "text"
        }
      ],
      "createdAt": "text",
      "dmMessage": "text",
      "emailGate": {
        "message": "text"
      },
      "followGate": {
        "buttonTitle": "I'm following",
        "message": "text"
      },
      "id": "text",
      "isActive": true,
      "name": "text",
      "platform": "facebook",
      "publishedVersionId": "text",
      "target": {
        "pageId": "text",
        "targetType": "facebook"
      },
      "triggers": [
        {
          "id": "text",
          "isActive": true,
          "keywords": [
            "text"
          ],
          "postId": "text",
          "type": "comment-received"
        }
      ],
      "updatedAt": "text",
      "webhook": {
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "method": "DELETE",
        "url": "text"
      },
      "stats": {
        "completed": 1,
        "failed": 1,
        "triggered": 1,
        "lastRunAt": "text"
      }
    }
  ],
  "cursor": "text"
}

Create a DM automation

post

Creates a DM automation: when any of its triggers fires it sends one direct message (text plus up to 3 link buttons). Pass triggers to start from several conditions; one matching event starts a single run. Set followGate (Instagram only) to gate that message behind a follow check, and emailGate to gate it behind the contact replying with an email address. Set webhook to call an external endpoint once the message is sent; every method except GET carries a JSON body with the contact's details, if known.

Authorizations
blotato-api-keystringRequired
Body
accountIdstringRequired
dmMessagestring · min: 1 · max: 640Required
isActivebooleanOptional
namestring · min: 1 · max: 60Required
platformstring · enumRequiredPossible values:
targetone ofRequired
or
triggersone of[] · max: 2Optional
or
Responses
201

Default Response

application/json
post/v2/dm-automations
POST /v2/dm-automations HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 471

{
  "accountId": "text",
  "buttons": [
    {
      "title": "text",
      "type": "url",
      "url": "text"
    }
  ],
  "dmMessage": "text",
  "emailGate": {
    "message": "text"
  },
  "followGate": {
    "buttonTitle": "I'm following",
    "message": "text"
  },
  "isActive": true,
  "name": "text",
  "platform": "facebook",
  "target": {
    "pageId": "text",
    "targetType": "facebook"
  },
  "triggers": [
    {
      "isActive": true,
      "keywords": [
        "text"
      ],
      "postId": "text",
      "type": "comment-received"
    }
  ],
  "webhook": {
    "headers": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "method": "DELETE",
    "url": "text"
  }
}
{
  "flow": {
    "accountId": "text",
    "buttons": [
      {
        "title": "text",
        "type": "url",
        "url": "text"
      }
    ],
    "createdAt": "text",
    "dmMessage": "text",
    "emailGate": {
      "message": "text"
    },
    "followGate": {
      "buttonTitle": "I'm following",
      "message": "text"
    },
    "id": "text",
    "isActive": true,
    "name": "text",
    "platform": "facebook",
    "publishedVersionId": "text",
    "target": {
      "pageId": "text",
      "targetType": "facebook"
    },
    "triggers": [
      {
        "id": "text",
        "isActive": true,
        "keywords": [
          "text"
        ],
        "postId": "text",
        "type": "comment-received"
      }
    ],
    "updatedAt": "text",
    "webhook": {
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "method": "DELETE",
      "url": "text"
    }
  }
}

Get a DM automation

get

Fetches a single DM automation by id, including its triggers and the message(s) it sends.

Authorizations
blotato-api-keystringRequired
Path parameters
idstringRequired
Responses
200

Default Response

application/json
get/v2/dm-automations/{id}
GET /v2/dm-automations/{id} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "flow": {
    "accountId": "text",
    "buttons": [
      {
        "title": "text",
        "type": "url",
        "url": "text"
      }
    ],
    "createdAt": "text",
    "dmMessage": "text",
    "emailGate": {
      "message": "text"
    },
    "followGate": {
      "buttonTitle": "I'm following",
      "message": "text"
    },
    "id": "text",
    "isActive": true,
    "name": "text",
    "platform": "facebook",
    "publishedVersionId": "text",
    "target": {
      "pageId": "text",
      "targetType": "facebook"
    },
    "triggers": [
      {
        "id": "text",
        "isActive": true,
        "keywords": [
          "text"
        ],
        "postId": "text",
        "type": "comment-received"
      }
    ],
    "updatedAt": "text",
    "webhook": {
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "method": "DELETE",
      "url": "text"
    }
  }
}

Delete a DM automation

delete

Archives a DM automation so its triggers stop listening and it no longer fires. Runs already in flight are unaffected.

Authorizations
blotato-api-keystringRequired
Path parameters
idstringRequired
Responses
200

Default Response

application/json
delete/v2/dm-automations/{id}
DELETE /v2/dm-automations/{id} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "flow": {
    "accountId": "text",
    "buttons": [
      {
        "title": "text",
        "type": "url",
        "url": "text"
      }
    ],
    "createdAt": "text",
    "dmMessage": "text",
    "emailGate": {
      "message": "text"
    },
    "followGate": {
      "buttonTitle": "I'm following",
      "message": "text"
    },
    "id": "text",
    "isActive": true,
    "name": "text",
    "platform": "facebook",
    "publishedVersionId": "text",
    "target": {
      "pageId": "text",
      "targetType": "facebook"
    },
    "triggers": [
      {
        "id": "text",
        "isActive": true,
        "keywords": [
          "text"
        ],
        "postId": "text",
        "type": "comment-received"
      }
    ],
    "updatedAt": "text",
    "webhook": {
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "method": "DELETE",
      "url": "text"
    }
  }
}

Update a DM automation

patch

Updates a DM automation. Each field present in the patch replaces that field; omitted fields are left unchanged. triggers replaces the whole trigger set ([] clears it). Pass null for emailGate, followGate, or webhook to remove it.

Authorizations
blotato-api-keystringRequired
Path parameters
idstringRequired
Body
Responses
200

Default Response

application/json
patch/v2/dm-automations/{id}
PATCH /v2/dm-automations/{id} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 389

{
  "patch": {
    "buttons": [
      {
        "title": "text",
        "type": "url",
        "url": "text"
      }
    ],
    "dmMessage": "text",
    "isActive": true,
    "name": "text",
    "triggers": [
      {
        "isActive": true,
        "keywords": [
          "text"
        ],
        "postId": "text",
        "type": "comment-received"
      }
    ],
    "emailGate": {
      "message": "text"
    },
    "followGate": {
      "buttonTitle": "I'm following",
      "message": "text"
    },
    "webhook": {
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "method": "DELETE",
      "url": "text"
    }
  }
}
{
  "flow": {
    "accountId": "text",
    "buttons": [
      {
        "title": "text",
        "type": "url",
        "url": "text"
      }
    ],
    "createdAt": "text",
    "dmMessage": "text",
    "emailGate": {
      "message": "text"
    },
    "followGate": {
      "buttonTitle": "I'm following",
      "message": "text"
    },
    "id": "text",
    "isActive": true,
    "name": "text",
    "platform": "facebook",
    "publishedVersionId": "text",
    "target": {
      "pageId": "text",
      "targetType": "facebook"
    },
    "triggers": [
      {
        "id": "text",
        "isActive": true,
        "keywords": [
          "text"
        ],
        "postId": "text",
        "type": "comment-received"
      }
    ],
    "updatedAt": "text",
    "webhook": {
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "method": "DELETE",
      "url": "text"
    }
  }
}

List DM automation runs

get

Lists the execution runs of a single DM automation, ordered by start time (most recent first). Supports cursor-based pagination.

Authorizations
blotato-api-keystringRequired
Path parameters
idstringRequired
Query parameters
limitinteger · min: 1 · max: 250Optional

Maximum number of execution runs to return. Defaults to 50.

Default: 50
cursorstringOptional

Opaque cursor returned by a previous call. Pass it to fetch the next page.

sincestring · date-timeOptional

Only return runs that have had some activity at or after this ISO 8601 timestamp.

Responses
200

Default Response

application/json
cursorstringOptional

Cursor for the next page. Absent when there are no more runs.

get/v2/dm-automations/{id}/runs
GET /v2/dm-automations/{id}/runs HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "contactId": "text",
      "createdAt": "text",
      "error": {
        "message": "text",
        "code": 1,
        "action": "text",
        "details": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "id": "text",
      "platform": "facebook",
      "status": "completed",
      "updatedAt": "text"
    }
  ],
  "cursor": "text"
}

List DM automation logs

get

Lists the execution logs written as a DM automation's runs progress, ordered by creation time (most recent first). Pass flowRunId to narrow the logs to a single run. Supports cursor-based pagination.

Authorizations
blotato-api-keystringRequired
Path parameters
idstringRequired
Query parameters
flowRunIdstringOptional

Only return logs belonging to this execution run. Omit to return logs across every run of the automation.

limitinteger · min: 1 · max: 250Optional

Maximum number of logs to return. Defaults to 50.

Default: 50
cursorstringOptional

Opaque cursor returned by a previous call. Pass it to fetch the next page.

Responses
200

Default Response

application/json
cursorstringOptional

Cursor for the next page. Absent when there are no more logs.

get/v2/dm-automations/{id}/logs
GET /v2/dm-automations/{id}/logs HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "items": [
    {
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "createdAt": "text",
      "flowRunId": "text",
      "id": "text",
      "level": "info",
      "message": "text",
      "nodeId": "text"
    }
  ],
  "cursor": "text"
}

Get DM automation analytics

get

Returns stats for a single DM automation.

Authorizations
blotato-api-keystringRequired
Path parameters
idstringRequired
Responses
200

Default Response

application/json
get/v2/dm-automations/{id}/analytics
GET /v2/dm-automations/{id}/analytics HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Accept: */*

{
  "analytics": {
    "completed": 1,
    "failed": 1,
    "issues": 1,
    "triggered": 1
  }
}

Update a DM automation trigger

patch

Turns one trigger of a DM automation on or off. It takes effect immediately on a live automation, and does not require an update to the flow. Pull the trigger ID from the automation's triggers. At least one trigger must stay active while the automation is live.

Authorizations
blotato-api-keystringRequired
Path parameters
flowIdstringRequired
triggerIdstringRequired
Body
Responses
200

Default Response

application/json
triggerone ofRequired
or
patch/v2/dm-automations/{flowId}/triggers/{triggerId}
PATCH /v2/dm-automations/{flowId}/triggers/{triggerId} HTTP/1.1
Host: backend.blotato.com
blotato-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "patch": {
    "isActive": true
  }
}
{
  "trigger": {
    "id": "text",
    "isActive": true,
    "keywords": [
      "text"
    ],
    "postId": "text",
    "type": "comment-received"
  }
}
PreviousComments
NextAutomation Templates

Last updated