> ## Documentation Index
> Fetch the complete documentation index at: https://docs.photon.codes/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use Stable documentation by default. Honor an explicit Beta request or a URL under /docs/beta/. If the requested version conflicts with the installed CLI package or API origin, clarify the target before writing integration code.
> Pages under /docs/beta/ document Beta; other product pages document Stable. Keep the CLI package, commands, API origin, and credentials within the selected version. State the documentation version in your answer.
> For MCP search, always pass version: Stable or version: Beta. Unfiltered search mixes both versions. For filesystem reads, keep Beta queries under /beta/ and exclude /beta/ from Stable queries; discover paths before reading them.
> The public docs base is https://photon.codes/docs. Convert MCP page paths to public URLs under that base, preserving /beta/ when present. Read https://photon.codes/docs/skill.md for version selection and https://photon.codes/docs/llms.txt for the version indexes.

# Inbound calls

> Register an inbound route and receive calls from a Spectrum iMessage line.

Inbound calling sends calls received by your Spectrum iMessage line to your
SIP application.

You must register inbound routing in the dashboard. Configuring outbound SIP
credentials does not create the inbound route automatically.

## Before you start

You need:

* A Spectrum project.
* An iMessage line in that project.
* A SIP application or phone system that can receive calls over TLS or TCP.
* A public hostname or IP address that Spectrum can reach.
* Firewall access (network permission) for the SIP listening port and the RTP
  audio ports used by your application.

WhatsApp numbers cannot be used for Spectrum Voice.

<Note>
  If the SIP application runs on a private network, such as a laptop on home or
  office Wi-Fi, it is not normally reachable from Spectrum. Configure port
  forwarding and firewall rules, or run the application on a public server.
</Note>

## Set up inbound calling

<Steps>
  <Step title="Open the project">
    Sign in to the [Spectrum dashboard](https://app.photon.codes) and select the
    project that owns the iMessage line.
  </Step>

  <Step title="Open inbound voice registration">
    Open the project's inbound voice registration and choose the iMessage line
    that should receive calls.

    Make sure you select an iMessage line. WhatsApp numbers are not supported.
  </Step>

  <Step title="Register the inbound route">
    In the **SIP URI** field, enter the address that Spectrum should call. Use
    `sips:` for encrypted TLS signaling or `sip:` for unencrypted TCP
    signaling:

    ```text theme={null}
    sips:agent@voice.example.com:5061
    sip:agent@voice.example.com:5060
    ```

    Replace `agent` with the SIP username or extension expected by your
    application, and replace `voice.example.com` with its public hostname.
    The final number is the port on which your application listens. A port tells
    Spectrum which network service to contact on that server.

    If the application does not require a specific username or extension, omit
    `agent@`. For example:

    ```text theme={null}
    sips:voice.example.com:5061
    ```

    Port 5061 is the default for `sips:` and 5060 is the default for `sip:`.
    These are defaults, not requirements. To use a different listening port,
    include that port in the URI. UDP is not supported.

    The dashboard also has optional **Username** and **Password** fields. Fill
    in both fields only if your SIP application requires username-and-password
    authentication for incoming calls. This standard SIP mechanism is called
    SIP Digest. Otherwise, leave both fields empty.
  </Step>

  <Step title="Configure your SIP application">
    Configure the application to listen using the same transport and port as
    the SIP URI saved in the dashboard.

    For TLS, the application needs a TLS certificate and its private key. For
    production, use a publicly trusted certificate that is valid for the
    hostname or IP address in the SIP URI. TCP does not require a TLS
    certificate.
  </Step>

  <Step title="Keep the SIP application available">
    Start the SIP application and make sure Spectrum can reach its public
    hostname or IP address and SIP port.

    Also allow the application's RTP port range through the firewall. RTP
    carries the call audio and normally uses UDP; check the application's media
    or RTP settings for its exact port range.
  </Step>

  <Step title="Place an inbound test call">
    From another phone, call the iMessage line registered in the dashboard.
    Confirm that your SIP application receives the call and that audio works in
    both directions.
  </Step>
</Steps>

## What each registration does

The word "registration" can refer to two different settings:

| Registration | Required? | Purpose |
| - | -: | - |
| Inbound route | Yes, for inbound calls | Routes calls from an iMessage line to your SIP application. |
| Business profile | No | Helps identify outbound traffic and reduce flagging risk. |

Registering a business profile does not create an inbound route. Registering
an inbound route does not register the business profile.

## Before going live

* The inbound route is saved under the correct project.
* The selected number is an iMessage line, not a WhatsApp number.
* The SIP application uses the routing values shown in the dashboard.
* The saved SIP URI uses `sips:` for TLS or `sip:` for TCP.
* The application listens on the transport and port specified by the saved SIP
  URI.
* The TLS certificate is valid for the hostname or IP address in the SIP URI
  when using TLS.
* Spectrum can reach the application's public hostname or IP address and SIP
  port.
* A test call reaches the application and has working two-way audio.
* The firewall allows the application's UDP RTP port range. SIP TLS does not
  encrypt the RTP audio stream.

## Troubleshooting

### No inbound call arrives

Check that the inbound route is saved for the exact iMessage line being called.
Then confirm that the SIP application is running, publicly reachable, and
listening on the transport and port specified by the saved SIP URI.

If the application runs behind a router or cloud firewall, confirm that traffic
on the SIP port is forwarded to the application.

### The wrong project or line receives the call

Open the inbound registration in the dashboard and verify both the selected
project and iMessage line. The inbound route is tied to that selection.

### The SIP application tries UDP

Select TLS or TCP explicitly in the SIP application. Spectrum Voice does not
accept SIP over UDP.

### A TLS route does not connect

Confirm that the route starts with `sips:`, the receiving application listens
for TLS on the configured port, and its certificate covers the hostname or IP
address in the route. Also confirm that the firewall allows inbound TCP traffic
on that port.

### The call arrives but audio does not work

SIP TLS protects signaling only. Audio uses RTP, so confirm that the endpoint's
firewall allows the UDP RTP port range configured in the SIP application. If
the application is behind a router, its NAT or port-forwarding configuration
must also send that traffic to the application. NAT is the router feature that
lets devices on a private network share a public internet address.

### I configured outbound calls, but inbound does not work

Outbound credentials and inbound routing are separate. Return to the dashboard
and register the inbound route for the iMessage line.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.