# Call External Method

The Call External Method action enables communication from Digia UI pages to native Flutter code. This action sends messages through the MessageBus to trigger native functionality or platform-specific operations. The payload supports any valid JSON data structure.

{% embed url="<https://www.youtube.com/watch?v=Fbu_W3O40x4>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=Fbu_W3O40x4>

## Properties

| Property  | Type     | Required | Description                                                                                                                                                                       |
| --------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`    | `string` | Yes      | The message name/channel to send to native code.                                                                                                                                  |
| `payload` | `object` | No       | Optional JSON object to send as parameters to the native handler. Individual property values can contain dynamic expressions, but the payload itself must be an object structure. |

## Examples

All payload data is automatically converted to JSON format before being sent to native code. The payload must be a JSON object where individual property values can contain dynamic expressions. Direct dynamic expressions for the entire payload are not supported.

### Basic Message Sending

<figure><img src="/files/Gvaj9jUkoYOJp0v7MWiC" alt="Call External Method action configuration showing message name and payload fields"><figcaption><p>Call External Method action configuration in Digia Studio</p></figcaption></figure>

***

Sends a message named "login" with user data to native code.

> **Note:** You cannot use dynamic expressions for both `name` and `payload` simultaneously. The payload must be a JSON object where individual property values can contain dynamic expressions, not a direct dynamic expression.

## Use Cases

* **Native API Integration**: Call device APIs not available in the UI framework
* **Platform-Specific Features**: Trigger camera, sensors, or hardware functionality
* **Analytics Tracking**: Send custom events to native analytics handlers
* **Third-Party Integration**: Communicate with Flutter packages from Digia Studio
* **Custom Processing**: Pass data to native code for specialized operations

## Default Behavior

By default:

| Behavior             | Description                                          |
| -------------------- | ---------------------------------------------------- |
| **Message Delivery** | Sends message immediately through MessageBus         |
| **Asynchronous**     | Action completes without waiting for native response |
| **No Feedback**      | No built-in UI feedback or confirmation              |
| **Handler Required** | Native code must implement DigiaMessageHandlerMixin  |

## How to Use

<figure><img src="/files/ZxiZC4m26KWj42s2qBd4" alt="Call External Method action configuration showing message name and payload fields"><figcaption><p>Call External Method action configuration in Digia Studio</p></figcaption></figure>

1. Attach the action to a widget event (button tap, form submission, etc.)
2. Select **Call External Method** from the action list
3. Specify the `name` that native code will listen for
4. Optionally provide `payload` data to send to the native handler

//TODO : Add gif

## Implementation Details

The action uses Flutter's MessageBus to send messages to native code. The payload is automatically JSON-serialized before transmission. Native widgets must implement `DigiaMessageHandlerMixin` to receive and handle these messages.

**Limitations:**

* You cannot use dynamic expressions for both `name` and `payload` simultaneously
* The payload must be a JSON object where individual property values can contain dynamic expressions
* Direct dynamic expressions like `"{{formData}}"` are not supported for payload

Example native implementation:

```dart
class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> with DigiaMessageHandlerMixin {
  @override
  void initState() {
    super.initState();
    addMessageHandler('login', _handleCustomAction);
  }

  void _handleCustomAction(Message message) {
    print('Received message with payload: ${message.payload}');
  }
}
```

Messages are sent asynchronously and the action completes immediately after sending, without waiting for native code response.

## Related Actions

* [Execute Callback](/logic-and-interaction/actions/execute-callback.md) - Call predefined callback functions
* [Fire Event](/logic-and-interaction/actions/fire-event.md) - Trigger analytics events
* [Set State](/logic-and-interaction/actions/set-state.md) - Update application state

***

*Asset Placeholder: Tutorial video demonstrating native method calls and MessageBus integration in Digia Studio*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/logic-and-interaction/actions/call-external-method.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.