Skip to main content
Use custom SIP headers to pass metadata between your systems and Retell on a call — for example, forwarding an account ID or a caller reference from your custom telephony platform so the agent can use it during the conversation.
SIP headers are available for phone calls only. Retell receives SIP headers on inbound calls, and sets them on outbound calls and transfers.
Many SIP parsers and middleboxes assume 1024 bytes is a reasonable maximum for a header line, and may reject or truncate longer headers unless configured to allow more.

​
Parse custom SIP headers for inbound calls

For inbound calls, custom SIP headers (those starting with X- or x-) are received and extracted automatically into call.custom_sip_headers. They are also added to your dynamic variables, where you access them by stripping the X- or x- prefix. No configuration is needed. For example, if this is the SIP header received for an inbound call:
Then here’s your call.custom_sip_headers field, and they will be added to your dynamic variables.
If you have already specified dynamic variables with the same name for this inbound call, it will override the value received from the SIP header.

​
Set custom SIP headers for outbound calls

Outbound call dialog with a custom SIP header key and value being added. For outbound calls, you can add custom SIP headers as needed. Each must start with X-.

​
Set custom SIP headers for call transfers

For call transfers, you can also add custom SIP headers as needed. Each must start with X-. You can use a dynamic variable for the header value to pass information extracted from the call to the receiving party.
For cold transfer with transferee number, it will use SIP REFER to transfer the call. Different telephony providers may or may NOT honor the custom SIP headers in the REFER request. Twilio for example, does not honor the custom SIP headers in the REFER request, so the SIP headers you set in the transfer call tool will not work for cold transfer with transferee number when using Twilio.
If you are using: