# 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-b86db2a74533407157f0d3113898d09f3d6c55e6%2Fcall_external_method_action.png?alt=media" 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="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-edca97c33550966f39b97bca6800c15a2170c6c5%2Fcall_external_method.gif?alt=media" 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](https://docs.digia.tech/logic-and-interaction/actions/execute-callback) - Call predefined callback functions
* [Fire Event](https://docs.digia.tech/logic-and-interaction/actions/fire-event) - Trigger analytics events
* [Set State](https://docs.digia.tech/logic-and-interaction/actions/set-state) - Update application state

***

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