Skip to main content

Callback Message Protocol

MaaAssistantArknights8/17/25About 6 min

Callback Message Protocol

Note

Callback messages are rapidly evolving with each version update, so this document may become outdated. For the latest information, please refer to the C# Integration Source Code

Callback Function Prototype

typedef void(ASST_CALL* AsstCallback)(int msg, const char* details, void* custom_arg);

Parameter Overview

  • int msg
    Message type

    enum class AsstMsg
{
    /* Global Info */
    InternalError     = 0,           // Internal error
    InitFailed        = 1,           // Initialization failed
    ConnectionInfo    = 2,           // Connection-related information
    AllTasksCompleted = 3,           // All tasks completed
    AsyncCallInfo     = 4,           // External asynchronous call information
    Destroyed         = 5,           // Instance destroyed

    /* TaskChain Info */
    TaskChainError     = 10000,      // Task chain execution/recognition error
    TaskChainStart     = 10001,      // Task chain started
    TaskChainCompleted = 10002,      // Task chain completed
    TaskChainExtraInfo = 10003,      // Task chain extra information
    TaskChainStopped   = 10004,      // Task chain manually stopped

    /* SubTask Info */
    SubTaskError      = 20000,       // Atomic task execution/recognition error
    SubTaskStart      = 20001,       // Atomic task started
    SubTaskCompleted  = 20002,       // Atomic task completed
    SubTaskExtraInfo  = 20003,       // Atomic task extra information
    SubTaskStopped    = 20004,       // Atomic task manually stopped

    /* Web Request */
    ReportRequest     = 30000,       // Report request
};

  • const char* details
    Message details, JSON string, see Field Explanations

  • void* custom_arg
    Custom parameter from the caller, returns the custom_arg parameter from the AsstCreateEx interface unchanged. C-like languages can use this parameter to pass this pointers

Field Explanations

InternalError

Todo

InitFailed

{
    "what": string,     // Error type
    "why": string,      // Error reason
    "details": object   // Error details
}

ConnectionInfo

{
    "what": string,     // Information type
    "why": string,      // Information reason
    "uuid": string,     // Device unique ID (empty when connection fails)
    "details": {
        "adb": string,     // AsstConnect interface adb_path parameter
        "address": string, // AsstConnect interface address parameter
        "config": string   // AsstConnect interface config parameter
    }
}

Common What Field Values

  • ConnectFailed
    Connection failed
  • Connected
    Connected, note that the uuid field is empty at this point (next step will retrieve it)
  • UuidGot
    Device unique ID retrieved
  • UnsupportedResolution
    Resolution not supported
  • ResolutionError
    Resolution retrieval error
  • Reconnecting
    Connection lost (adb/emulator crashed), attempting reconnection
  • Reconnected
    Connection lost (adb/emulator crashed), reconnection successful
  • Disconnect
    Connection lost (adb/emulator crashed), and reconnection failed
  • ScreencapFailed
    Screenshot failed (adb/emulator crashed), and retry failed
  • TouchModeNotAvailable
    Unsupported touch mode

AsyncCallInfo

{
    "uuid": string,             // Device unique ID
    "what": string,             // Callback type, "Connect" | "Click" | "Screencap" | ...
    "async_call_id": int,       // Asynchronous request ID, i.e., return value when calling AsstAsyncXXX
    "details": {
        "ret": bool,            // Actual call return value
        "cost": int64,          // Time cost, in milliseconds
    }
}

AllTasksCompleted

{
    "taskchain": string,            // Last task chain
    "uuid": string,                 // Device unique ID
    "finished_tasks": [             // IDs of tasks that have been run
        int,
        ...
    ]
}

Common taskchain Field Values

  • StartUp
    Start up
  • CloseDown
    Close down
  • Fight
    Sanity farming
  • Mall
    Credit store and shopping
  • Recruit
    Auto recruitment
  • Infrast
    Base management
  • Award
    Collect daily rewards
  • Roguelike
    Integrated Strategy
  • Copilot
    Auto combat
  • SSSCopilot
    Auto Stationary Security Service
  • Depot
    Depot recognition
  • OperBox
    Operator box recognition
  • Reclamation
    Reclamation Algorithm
  • Custom
    Custom task
  • SingleStep
    Single step task
  • VideoRecognition
    Video recognition task
  • Debug
    Debug
{
    "taskchain": string,            // Current task chain
    "taskid": int,                  // Current task TaskId
    "uuid": string                  // Device unique ID
}

TaskChainExtraInfo

Todo

{
    "subtask": string,             // Subtask name
    "class": string,               // Subtask symbol name
    "taskchain": string,           // Current task chain
    "taskid": int,                 // Current task TaskId
    "details": object,             // Details
    "uuid": string                 // Device unique ID
}

Common subtask Field Values

  • ProcessTask

    // Corresponding details field example
{
  "task": "StartButton2", // Task name
  "action": 512,
  "exec_times": 1, // Execution times
  "max_times": 999, // Maximum execution times
  "algorithm": 0
}

  • Todo others

Common task Field Values
  • StartButton2
    Start battle
  • MedicineConfirm
    Use sanity potion
  • ExpiringMedicineConfirm
    Use sanity potion expiring within 48 hours
  • StoneConfirm
    Use Originium Prime
  • RecruitRefreshConfirm
    Refresh recruitment tags
  • RecruitConfirm
    Confirm recruitment
  • RecruitNowConfirm
    Use Expedited Plan
  • ReportToPenguinStats
    Report to Penguin Statistics
  • ReportToYituliu
    Report to Yituliu big data
  • InfrastDormDoubleConfirmButton
    Base dormitory double confirmation button, appears only when operators conflict, please notify users
  • StartExplore
    Start Integrated Strategy exploration
  • StageTraderInvestConfirm
    Integrated Strategy invested Originium Ingots
  • StageTraderInvestSystemFull
    Integrated Strategy investment reached game limit
  • ExitThenAbandon
    Integrated Strategy abandoned current exploration
  • MissionCompletedFlag
    Integrated Strategy battle completed
  • MissionFailedFlag
    Integrated Strategy battle failed
  • StageTraderEnter
    Integrated Strategy stage: Merchant
  • StageSafeHouseEnter
    Integrated Strategy stage: Safe House
  • StageEncounterEnter
    Integrated Strategy stage: Encounter/Castle Gift
  • StageCombatDpsEnter
    Integrated Strategy stage: Combat
  • StageEmergencyDps
    Integrated Strategy stage: Emergency Combat
  • StageDreadfulFoe
    Integrated Strategy stage: Dreadful Foe
  • StartGameTask
    Failed to open client (config file does not match passed client_type)
  • Todo others

SubTaskExtraInfo

{
    "taskchain": string,           // Current task chain
    "class": string,               // Subtask type
    "what": string,                // Information type
    "details": object,             // Information details
    "uuid": string,                // Device unique ID
}

Common what and details Field Values

  • StageDrops
    Stage material drop information

    // Corresponding details field example
{
  "drops": [
    // Materials dropped in this recognition
    {
      "itemId": "3301",
      "quantity": 2,
      "itemName": "技巧概要·卷1" // "Skill Summary - 1"
    },
    {
      "itemId": "3302",
      "quantity": 1,
      "itemName": "技巧概要·卷2" // "Skill Summary - 2"
    },
    {
      "itemId": "3303",
      "quantity": 2,
      "itemName": "技巧概要·卷3" // "Skill Summary - 3"
    }
  ],
  "stage": {
    // Stage information
    "stageCode": "CA-5",
    "stageId": "wk_fly_5"
  },
  "stars": 3, // Operation completion stars
  "stats": [
    // Total material drops during this execution
    {
      "itemId": "3301",
      "itemName": "技巧概要·卷1", // "Skill Summary - 1"
      "quantity": 4,
      "addQuantity": 2 // New drop quantity this time
    },
    {
      "itemId": "3302",
      "itemName": "技巧概要·卷2", // "Skill Summary - 2"
      "quantity": 3,
      "addQuantity": 1
    },
    {
      "itemId": "3303",
      "itemName": "技巧概要·卷3", // "Skill Summary - 3"
      "quantity": 4,
      "addQuantity": 2
    }
  ]
}

  • RecruitTagsDetected
    Recruitment tags detected

    // Corresponding details field example
{
  "tags": ["费用回复", "防护", "先锋干员", "辅助干员", "近战位"] // ["DP-Recovery", "Defense", "Vanguard", "Support", "Melee"]
}

  • RecruitSpecialTag
    Recruitment special tag detected

    // Corresponding details field example
{
  "tag": "高级资深干员" // "Top Operator"
}

  • RecruitResult
    Recruitment recognition result

    // Corresponding details field example
{
  "tags": [
    // All detected tags, currently always 5
    "削弱", // "Debuff"
    "减速", // "Slow"
    "术师干员", // "Caster"
    "辅助干员", // "Supporter"
    "近战位" // "Melee"
  ],
  "level": 4, // Overall rarity
  "result": [
    {
      "tags": ["削弱"], // ["Debuff"]
      "level": 4, // This tag combination's rarity
      "opers": [
        {
          "name": "初雪", // "Pramanix"
          "level": 5 // Operator rarity
        },
        {
          "name": "陨星", // "Meteorite"
          "level": 5
        },
        {
          "name": "槐琥", // "Waai Fu"
          "level": 5
        },
        {
          "name": "夜烟", // "Haze"
          "level": 4
        },
        {
          "name": "流星", // "Meteor"
          "level": 4
        }
      ]
    },
    {
      "tags": ["减速", "术师干员"], // ["Slow", "Caster"]
      "level": 4,
      "opers": [
        {
          "name": "夜魔", // "Nightmare"
          "level": 5
        },
        {
          "name": "格雷伊", // "Greyy"
          "level": 4
        }
      ]
    },
    {
      "tags": ["削弱", "术师干员"], // ["Debuff", "Caster"]
      "level": 4,
      "opers": [
        {
          "name": "夜烟", // "Haze"
          "level": 4
        }
      ]
    }
  ]
}

  • RecruitTagsRefreshed
    Recruitment tags refreshed

    // Corresponding details field example
{
  "count": 1, // Current slot refresh count
  "refresh_limit": 3 // Current slot refresh limit
}

  • RecruitNoPermit
    No recruitment permits available

    // Corresponding details field example
{
  "continue": true // Whether to continue refreshing
}

  • RecruitTagsSelected
    Recruitment tags selected

    // Corresponding details field example
{
  "tags": ["减速", "术师干员"] // ["Slow", "Caster"]
}

  • RecruitSlotCompleted
    Current recruitment slot task completed

  • RecruitError
    Recruitment recognition error

  • EnterFacility
    Base entered facility

    // Corresponding details field example
{
  "facility": "Mfg", // Facility name
  "index": 0 // Facility index
}

  • NotEnoughStaff
    Base available operators insufficient

    // Corresponding details field example
{
  "facility": "Mfg", // Facility name
  "index": 0 // Facility index
}

  • ProductOfFacility
    Base facility product

    // Corresponding details field example
{
  "product": "Money", // Product name
  "facility": "Mfg", // Facility name
  "index": 0 // Facility index
}

  • StageInfo
    Auto combat stage information

    // Corresponding details field example
{
    "name": string  // Stage name
}

  • StageInfoError
    Auto combat stage recognition error

  • PenguinId
    Penguin Statistics ID

    // Corresponding details field example
{
    "id": string
}

  • Depot
    Depot recognition result

    // Corresponding details field example
"done": bool,       // Whether recognition is complete, false means still in progress (data during process)
"arkplanner": {     // https://penguin-stats.cn/planner
    "object": {
        "items": [
            {
                "id": "2004",
                "have": 4,
                "name": "高级作战记录" // "Advanced Battle Record"
            },
            {
                "id": "mod_unlock_token",
                "have": 25,
                "name": "模组数据块" // "Module Data Block"
            },
            {
                "id": "2003",
                "have": 20,
                "name": "中级作战记录" // "Tactical Battle Record"
            }
        ],
        "@type": "@penguin-statistics/depot"
    },
    "data": "{\"@type\":\"@penguin-statistics/depot\",\"items\":[{\"id\":\"2004\",\"have\":4,\"name\":\"高级作战记录\"},{\"id\":\"mod_unlock_token\",\"have\":25,\"name\":\"模组数据块\"},{\"id\":\"2003\",\"have\":20,\"name\":\"中级作战记录\"}]}"
},
"lolicon": {     // https://arkntools.app/#/material
    "object": {
        "2004" : 4,
        "mod_unlock_token": 25,
        "2003": 20
    },
    "data": "{\"2003\":20,\"2004\": 4,\"mod_unlock_token\": 25}"
}
// Currently only supports ArkPlanner and Lolicon (Arkntools) formats, may support more websites in the future

  • OperBox
    Operator recognition result

    // Corresponding details field example
"done": bool,       // Whether recognition is complete, false means still in progress (data during process)
"all_oper": [
    {
        "id": "char_002_amiya",
        "name": "阿米娅", // "Amiya"
        "own": true,
        "rarity": 5
    },
    {
        "id": "char_003_kalts",
        "name": "凯尔希", // "Kal'tsit"
        "own": true,
        "rarity": 6
    },
    {
        "id": "char_1020_reed2",
        "name": "焰影苇草", // "Reed the Flame Shadow"
        "own": false,
        "rarity": 6
    },
]
"own_opers": [
    {
        "id": "char_002_amiya", // Operator ID
        "name": "阿米娅", // "Amiya" - Operator name
        "own": true, // Whether owned
        "elite": 2, // Elite level 0,1,2
        "level": 50, // Operator level
        "potential": 6, // Operator potential [1, 6]
        "rarity": 5 // Operator rarity [1, 6]
    },
    {
        "id": "char_003_kalts",
        "name": "凯尔希", // "Kal'tsit"
        "own": true,
        "elite": 2,
        "level": 50,
        "potential": 1,
        "rarity": 6
    }
]

  • UnsupportedLevel
    Auto combat, unsupported stage name

ReportRequest

This field is mainly used by the core module to pass network request information to the UI layer, which is responsible for performing the actual HTTP reporting operations.

{
  "url": "string",            // The full request URL, e.g., https://penguin-stats.io/PenguinStats/api/v2/report
  "headers": {                // Request headers key-value pairs (excluding Content-Type, which is added by the UI)
    "authorization": "PenguinID 1234567890",
    "User-Agent": "MaaAssistantArknights/1.2.3 cpr/4.5.6"
  },
  "body": "string",           // Request body content (usually a JSON-formatted string)
  "subtask": "string"         // Subtask name identifying the specific reporting task, e.g., "ReportToPenguinStats", "ReportToYituliu"
}