---
name: kimaai_leads_capability
type: filter
since: 1.6.0
tier: free
feature: lead-capture
area: leads-customer-centre
summary: Changes the capability a user needs to see, export and delete leads.
parameters:
  - name: capability
    type: string
    description: The capability, manage_options by default.
returns:
  type: string
  description: The capability to check. A non-string or blank answer counts as manage_options.
---

# kimaai_leads_capability

## When it fires

Whenever KimaAI checks who may see the leads: for the Leads page in the admin, its REST routes (the list, a lead's conversation, deleting a lead), the CSV export, and the error texts of failed lead deliveries, which can quote a lead's details. The filter gets no user: return a capability, and WordPress checks it for the current user.

Leads are personal data. Whoever has the capability reads every lead with its conversation, exports and deletes them, so give it only to the people who handle leads. An answer that is not a string or is blank falls back to `manage_options`, so a broken callback never opens the leads to everyone. The rest of KimaAI's admin, settings included, still needs `manage_options`.

## Example

```php
add_filter(
  'kimaai_leads_capability',
  function (): string {
    return 'view_sales_leads';
  }
);
```

WordPress gives an own capability to no role, administrators included. Add it once to the roles that handle leads, for example when your plugin is activated:

```php
register_activation_hook(
  __FILE__,
  function (): void {
    foreach (['administrator', 'sales_manager'] as $role_name) {
      $role = get_role($role_name);
      if ($role) {
        $role->add_cap('view_sales_leads');
      }
    }
  }
);
```

## Related

- `kimaai_lead_saved`: fires when a lead was stored.
- `kimaai_lead_erased`: fires when a lead's details were erased or the lead was deleted.
