# `Caracola.Refer`
[🔗](https://github.com/netkubes/caracola/blob/v0.1.0-rc.1/lib/caracola/refer.ex#L1)

REFER (RFC 3515, call transfer). Equivalent to NkSIP's `nksip_refer`.

```
defmodule MyUA do
  use Malla.Service, plugins: [Caracola.Refer], sip: [listen: "sip:all:5060"]

  defcb sip_refer(_refer_to, _req, _call), do: true
end
```

REFER requests are sent with `Caracola.UAC.refer/3` and the
`{:refer_to, uri}` option, out of a dialog or in one. The `:subscription`
meta of the response is the implicit subscription, which gets NOTIFYs with
the progress of the referred request as `message/sipfrag` bodies.

When a REFER arrives, the plugin calls `sip_refer(refer_to, req, call)`.
If it returns `true` the REFER is accepted (202) and an INVITE is sent to
`refer_to` (with `:auto_2xx_ack` and Call-ID `"caracola_refer_" <>
call_id`); each response to it is notified to the referrer, and the
subscription is terminated with the final one. `false` (the default)
rejects it with 403.

The referrer is told about the subscription with
`sip_refer_update(subscription, status, call)`, where `status` is `:init`,
`:active`, `:middle_timer`, `{:notify, sipfrag}` for each NOTIFY or
`:terminated`.

Any request (not only an INVITE) can report to a REFER subscription with
the `{:refer_subscription, handle}` option of `Caracola.UAC`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
