Interception

Interceptors allow you to plug custom logic into a channel connection at the ADK level to process and transform messages flowing through channels in real-time. Interceptors act as programmable filters in the message pipeline, enabling custom business logic, validation, transformation, and integration with external systems.

note

We suggest you understand the core concepts of Interceptor before diving into this section. To learn more about interceptors, click here

How to intercept

Interceptors can be integrated into the message pipeline at any required place using the orchestrator. While creating a channel, if the Enable Orchestrator option is checked, the flow of the message through the pipeline is decided by the orchestrator, which creates a flow chart of operations as nodes.

warning

A channel can only be intercepted if the orchestrator is enabled at creation. It cannot be changed later.

You can learn more about Message orchestration and configuring the orchestrator from the Agent Builder Documentation.

There are two types of interceptors based on the execution model:

1. Synchronous interceptor — Pipeline waits for interceptor completion
2. Asynchronous interceptor — Pipeline continues while interceptor processes

// Synchronous interceptor
[adk intercept:@"my-interceptor"
            fn:^(NSDictionary *payload, void (^resolve)(id), void (^reject)(NSString *)) {
                
                id data = payload[@"data"];
                if (data) {
                    resolve(@{
                        @"status": @"success",
                        @"data": data
                    });
                } else {
                    reject(@"Failed");
                }
            }
    completion:^(Interception *interception, NSError *error) {
        if (error) {
            NSLog(@"Failed to register interceptor: %@", error);
        }
    }];

// Asynchronous interceptor
[adk intercept:@"my-interceptor"
            fn:^(NSDictionary *payload, void (^resolve)(id), void (^reject)(NSString *)) {
                
                // Run async work without blocking pipeline
                dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
                    NSLog(@"🔀 Intercepted: on %@", payload);
                    
                    // Simulate async work (API call, DB, etc.)
                    // id result = [self someAsyncFunction:payload];
                    
                    resolve(payload);
                });
            }
    completion:^(Interception *interception, NSError *error) {
        if (error) {
            NSLog(@"Failed to register interceptor: %@", error);
        }
    }];

important

Encrypted channel types cannot be intercepted — ART preserves complete privacy of user data on those channels.