# useCall

A hook for calling a contract message and decoding a successful response or receiving an error. See [useink/utils helpers](https://use.ink/frontend/utils/pick) for compatible functions that work well with this hook.

### Usage[​](https://use.ink/frontend/react/hooks/contracts/use-call#usage) <a href="#usage" id="usage"></a>

```javascript
import { useCall } from 'useink'
import { pickDecoded } from 'useink/utils'
import metadata from 'contract/metadata.json'

const CONTRACT_ADDRESS = '...'

// We define a response type so that `get.result.value.decoded` is of type SuccessfulResponse
interface SuccessfulResponse {
  foo: 'bar'
}

export const MyContractView: React.FC = () => {
  const contract = useContract(CONTRACT_ADDRESS, metadata, 'astar');
  const get = useCall<SuccessfulResponse>(contract, 'get');
  const args = ['arg-1', 2];

  return (
    <>
      <h1>Get the Result the hard way: {get.result?.ok ? get.result.value.decoded.foo : '--'}</h1>
      <h1>Or the easy way: {pickDecoded(get.result)?.foo || '--'}</h1>

      <button disabled={get.isSubmitting} onClick={() => get.send(args)}>
        Get Result
      </button>
    </>
  );
}
```

### Calling with a default caller address[​](https://use.ink/frontend/react/hooks/contracts/use-call#calling-with-a-default-caller-address) <a href="#calling-with-a-default-caller-address" id="calling-with-a-default-caller-address"></a>

You must first define a default caller in [configuration](https://use.ink/frontend/configuration#configprops), then call the contract with options:

```javascript
const call = useCall(contract, 'get');
const args = [];

call.send(args, { defaultCaller: true })
```

### Handling `Result<T, E>` responses from an ink! contract[​](https://use.ink/frontend/react/hooks/contracts/use-call#handling-resultt-e-responses-from-an-ink-contract) <a href="#handling-resultt-e-responses-from-an-ink-contract" id="handling-resultt-e-responses-from-an-ink-contract"></a>

One of the benefits of using ink! is ability to return meaningful errors with `Result<T, E>` (since ink! v4.0.0). In this example we will distinguish between two kinds of errors and a successful result. Let's say that you have the following ink! code in your contract.

```javascript
    use ink::prelude::string::String;

    // ...other contract code omitted

    #[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)]
    #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
    pub struct Unhappy {
        boo: String,
    }

    // A successful response
    #[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)]
    #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
    pub struct Happy {
        yippee: String,
    }

    #[derive(Debug, PartialEq, Eq, scale::Encode, scale::Decode)]
    #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
    pub enum Error {
        Sad(Unhappy),
    }

    impl MyMoodyContract {
      #[ink(message)]
      pub fn mood(&self, value: u64) -> Result<Happy, Error> {
          if value % 2 == 0 {
              return Ok(Happy {
                  yippee: String::from("😃"),
              });
          }

          Err(Error::Sad(Unhappy {
              boo: String::from("😢"),
          }))
      }
    }
```

In this example, when you call `mood(2)`, you will get an `Ok` response. If you call `mood(1)` you will get an `Err`. If you call `mood(5)` you will get another type of `Err`.

Here is how we could handle the view using **useink**.

```javascript
import { useCall, useContract, useBlockNumber, decodeError } from 'useink'
import metadata from 'contract/metadata.json'
const CONTRACT_ADDRESS = '...'

// We define the interface for the response.
interface MoodResult { 
  Ok?: { yippee: string }; 
  Err?: { 
    Sad?: { boo: string; },
  },
};

export const MyFickleContract: React.FC = () => {
  const { blockNumber } = useBlockNumber();
  const contract = useContract(CONTRACT_ADDRESS, metadata);
  const getMood = useCall<MoodResult>(contract, 'mood');

  // Fetch the mood of the contract on each new block
  useEffect(() => {
    if(blockNumber) getMood.send([blockNumber]);
  }, [blockNumber])

  // result is undefined before it is called the first time
  if (!getMood.result) return <h1>Loading...</h1>

  // if result.ok is false then one of two things happened.
  // One possibility is that a pallet in the Substrate runtime threw an error.
  // A second possibility is a contract method may have called panic! 
  // OR called assert! and it failed. In these situations no Response has been returned. 
  // We need to handle the error using decodeError.
  if (!getMood.result.ok) {
    return (
      <div>
        <p>An error occurred in runtime, not our contract function.</p>
        <p>
          {decodeError(getMood, {
            ContractTrapped: 'This is a custom message. Something went wrong.', 
          })}
        </p>
      </div>
    )
  }

  // We now know we have decoded value of type `MoodResult`
  const { decoded } = getMood.result.value;

  return (
    <h1>
      Block Number {blockNumber} makes me feel
      {decoded.Ok && decoded.Ok.yippee}
      {decoded.Err?.Sad && decoded.Err.Sad.boo}
    </h1>
  );
}
```

### Return Value[​](https://use.ink/frontend/react/hooks/contracts/use-call#return-value) <a href="#return-value" id="return-value"></a>

```javascript
type DecodedContractResult<T> = {
  result?: {
    ok: true;
    value: {
      decoded: T; // The response is decoded using contract Metadata and of type `T`
      raw: ContractExecResult; // encoded raw data 
    } | {
      ok: false;
      // error
      // This error occurs if any pallet throws an error, 
      // or if a contract method calls panic! or assert!() and it fails.
      error: DispatchError | undefined; 
    }
  }
}

// useCall returns
{
  isSubmitting: boolean;
  // args: a list of arguments your contract message receives
  // options: additional option overrides
  // caller: the calling address. This can be used in ink! contracts with `self.env.caller()`
  //         `caller` defaults to the connected wallet address.
  send: (args?: unknown[], options?: ContractOptions, caller?: string) => 
    Promise<DecodedContractResult<T> | undefined>;
  result?: DecodedContractResult<T>;
}
```


---

# 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://lunes-labs.gitbook.io/dao-lunes-labs-pt/developers/para-desenvolvedores/smart-contract-ink-4.x/frontend-development/hooks/contracts/usecall.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.