This will update properties and functionality for a given FoneNumber, including its label, group, call recording settings, and various options to control voice, SMS, and fax services.

A successful call will respond with a FoneNumber object.

Notes

`label`

This is an optional descriptive string that is attached to the FoneNumber. It is not used by FoneStorm in any capacity, but will be remembered and returned with the FoneNumber.

`group`

This is an identifier which can be use to group together FoneNumbers in an account.

`record_calls`

Setting this value controls whether phone calls made to or from this FoneNumber are recorded. Available values are:

Value	Result
`Default`	Uses the account setting
`Yes`	Records calls made to and from this FoneNumber
`No`	Does not record any calls
`InBound`	Records calls made to this FoneNumber
`OutBound`	Records calls made from this FoneNumber

`call_options`

`receive`

These options allows the application developer to programmatically and dynamically configure the service type to be provided for inbound phone calls that are made to a FoneNumber on a users account. The Service Type can be one of several destination options: Forward to another telephone number, send the call to a configured and registered SIP Device (e.g. handset, FracTELfone app, etc.), connect to a properly configured FracTEL Feature (IVR, Fax2email, VoiceMail, etc.), play a specified audio file and more. There are also options for standard no-answer call dispositions (Reject, Hangup or Busy). Use the type parameter to specify the Service Type, and value to provide the additional data required to specify the service. The table below summarizes available options, see Service Types for more information on Service Types and the configuration and use of a FracTEL Feature.

type

Use the type parameter to specify the type of destination. Available types are Device, Forward, Conference, IVR, Scheduler, Fax, VoiceMail, Monetizer, Reject, Hangup, and Busy. For more information, see Service Types.

value

The value parameter contains the corresponding setting for the destination. value is REQUIRED unless type is Reject, Hangup or Busy. For more information, see Service Types.

Type	Value	Example
Hangup	Hangup incoming call
Reject	Reject incoming call
Busy	Send busy signal to the incoming call
Device	The ID for the destination device	987123543678
Forward	A forwarding phone number	3215551111
IVRMenu	The ID for the destination IVRMenu	456123543678
Scheduler	The ID for the destination Scheduler	123123543678
Voicemail	The ID for the destination Voicemail Box	298123543678

`receive_notify` or `send_notify`

This setting is used to set up the notification whenever an incoming call is received or outbound call is made. Notifications can be received on an Email or on a Callback URL.

type

The notification configuration can be set to None, 'Callback', or 'Email'. Using None will clear any existing notification setting. Using Callback will result on a webhook being called to report the event, while using Email generates an email.

Email Configuration

email

If the type is set to Email, then this parameter containing the destination address will receive an email message containing event information in the body. Only a single email address is supported at this time.

Callback Configuration

url

The url parameter contains the URL to be called when the event takes place. The full URL, including the protocol (https://) needs to be provided (URLs with valid SSL certificates are supported only.). Tokens for data substitution can also be included; for more information see the Data Handling section

method

This parameter specifies the methods used for the callback and its data.

GET returns data through query string parameters on a GET to the given URL.
POST returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/x-www-form-urlencoded
JSON returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/json

For information on data encoding formats, see the Data Handling section.

url_username, url_password

Callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

Data Handling

Each type of method provides a different way of transmitting data associated with the callback. A full listing of available data and an explanation of their values is provided with the specific callback's documentation.

GET

If the method is GET, FoneStorm will apply token substitution to the value provided in url.

Example

If the url for a messages/receive_notify callback is https://my.example.com/notify.php?direction=((direction)), the ((direction)) token will be replaced with the direction of the call. The actual callback URL that is executed would be something like https://my.example.com/notify.php?direction=OUTBOUND

Parameter	Type	Description
account_code	string	Account billed for call
direction	string	`OUTBOUND` or `INBOUND`
status	string	`BEGIN` or `END`
from	string	Caller id.
to	string	Call destination.
type	string	`VOICE`
disposition	string	One of the following: `ANSWERED` `NO_ANSWER` `REJECTED` `BUSY` `CANCEL` `INVALID` `FAILED` `FAILED:###`
billable_seconds	number	Number of seconds billable for the call
id	string	Unique identifier for the call.

POST

If the method is POST, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON.

Example

If the url for the callback is https://my.example.com/notify.php, the body for the callback request will contain a string like {"to":"3215551212","from":"3215551111","account_code":"2005559999","id":"0c4055acc5cc2736d818c96f4421b2f5","billable_seconds":"100","direction":"OUTBOUND","status":"END","type":"VOICE","disposition":"ANSWERED"}.

JSON

If the method is JSON, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON Object.

Example

If the url for the callback is https://my.example.com/notify.php, the body for the callback request will contain a JSON Object like

{ 
    "to": "3215551212",
    "from": "3215551111",
    "account_code" :"2005559999",
    "id": "0c4055acc5cc2736d818c96f4421b2f5",
    "billable_seconds": 100,
    "direction": "OUTBOUND",
    "status": "END",
    "type": "VOICE",
    "disposition": "ANSWERED"
}

url_username, url_password

Callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

For more information, see Callbacks / Web Hooks.

The structure for call_options is shown below.

{
    receive: {
        type:
        value:
    }
    receive_notify: {
        type:
        url:
        method:
        url_username:
        url_password:
        email:
    }
    send_notify: {
        type:
        url:
        method:
        url_username:
        url_password:
        email:      
    }
}

`message_options`

`enable_messaging`

This parameter is used to enable or disable messaging on a FoneNumber. Values for this parameter can be True or False. True will enable messaging on the FoneNumber and False will disable messaging on the FoneNumber.

`receive`

These options allows the application developer to programmatically and dynamically configure the service type to be provided for inbound messages that are made to a FoneNumber on a users account. The Service Type can be one of several destination options: Forward to another telephone number, send the message to a configured and registered SIP Device (e.g. handset, FracTELfone app, etc.), Send it to an Email address, Send it to a Webhook URL. Use the type parameter to specify the Service Type, and value to provide the additional data required to specify the service.

type

Use the type parameter to specify the type of destination. Available types are Device, Forward, Email, Forward and None.

value

The value parameter contains the corresponding setting for the destination. value is REQUIRED unless type is None.

Type	Value	Example
None	Clear the message destination setting
Device	The ID for the destination device	987123543678
Forward	A forwarding phone number	3215551111
Email	The Email address for the message forwarding	support@fractel.com
URL	Webhook URL for the message forwarding	https://my.example.com/notify.php?message=((msg))

url_method

This parameter specifies the methods used for the callback and its data.

GET returns data through query string parameters on a GET to the given URL.
POST returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/x-www-form-urlencoded
JSON returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/json

For information on data encoding formats, see the Data Handling section.

url_username, url_password

Callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

`receive_notify` or `send_notify`

This setting is used to set up the notification whenever an inbound message is received or outbound message is sent. Notifications can be received on an Email or on a Callback URL.

type

The notification configuration can be set to None, 'Callback', or 'Email'. Using None will clear any existing notification setting. Using Callback will result on a webhook being called to report the event, while using Email generates an email.

Email Configuration

email

If the type is set to Email, then this parameter containing the destination address will receive an email message containing event information in the body. Only a single email address is supported at this time.

Callback Configuration

url

The url parameter contains the URL to be called when the event takes place. The full URL, including the protocol (https://) needs to be provided (URLs with valid SSL certificates are supported only.). Tokens for data substitution can also be included; for more information see the Data Handling section

method

This parameter specifies the methods used for the callback and its data.

GET returns data through query string parameters on a GET to the given URL.
POST returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/x-www-form-urlencoded
JSON returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/json

For information on data encoding formats, see the Data Handling section.

url_username, url_password

Callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

Data Handling

Each type of method provides a different way of transmitting data associated with the callback. A full listing of available data and an explanation of their values is provided with the specific callback's documentation.

GET

If the method is GET, FoneStorm will apply token substitution to the value provided in url.

Example

If the url for a messages/receive_notify callback is https://my.example.com/notify.php?id=((id))&to=((to))&from=((from))&msg=((msg))&media=((media))&status=((status))&status_message=((status_message))&segments=((segments)), the tokens like ((id)) will be replaced with the id of the message. The actual callback URL that is executed would be something like https://my.example.com/notify.php?to=3215551212&from=3215551111&msg=Test&id=0c4055acc5cc2736d818c96f4421b2f5&media=https://example.com/image.png&status=SUCESS&status_message=Sent&segments=1

Parameter	Type	Description
from	string	Message origination number.
to	string	Message destination number.
msg	string	Test message
media	string	https://example.com/image.png
id	string	Unique identifier for the message.
status	string	Status of the message SUCCESS or FAILED.
status_message	string	Additional message with status.
segments	string	Number of segments calculated from message text.

POST

If the method is POST, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON.

Example

If the url for the callback is https://my.example.com/notify.php, the body for the callback request will contain a string like {"to":"3215551212","from":"3215551111","msg":"Test message","id":"0c4055acc5cc2736d818c96f4421b2f5","media":"https://example.com/image.png","status": "SUCESS","status_message": "Sent to device 34033","segments" : 1}.

JSON

If the method is JSON, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON Object.

Example

If the url for the callback is https://my.example.com/notify.php, the body for the callback request will contain a JSON Object like

{ 
    "to": "3215551212",
    "from": "3215551111",
    "msg": "Test message",
    "id": "0c4055acc5cc2736d818c96f4421b2f5",
    "media": "https://example.com/image.png",
    "status": "SUCESS",
    "status_message": "Sent to device 34033",
    "segments" : 1
}

url_username, url_password

Callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

For more information, see Callbacks / Web Hooks.

The structure for message_options is shown below.

{
    receive: {
        type:
        value:
        url_method:
        url_username:
        url_password:
    }
    receive_notify: {
        type:
        url:
        method:
        url_username:
        url_password:
        email:
    }
    send_notify: {
        type:
        url:
        method:
        url_username:
        url_password:
        email:      
    },
    enable_messaging:
}

`fax_options`

`receive_notify` or `send_notify`

This setting is used to set up the notification whenever an incoming fax is received or outbound fax is sent. Notifications can be received on an Email or on a Callback URL.

type

The notification configuration can be set to None, 'Callback', or 'Email'. Using None will clear any existing notification setting. Using Callback will result on a webhook being called to report the event, while using Email generates an email.

Email Configuration

email

If the type is set to Email, then this parameter containing the destination address will receive an email message containing event information in the body. Only a single email address is supported at this time.

Callback Configuration

url

The url parameter contains the URL to be called when the event takes place. The full URL, including the protocol (https://) needs to be provided (URLs with valid SSL certificates are supported only.). Tokens for data substitution can also be included; for more information see the Data Handling section

method

This parameter specifies the methods used for the callback and its data.

GET returns data through query string parameters on a GET to the given URL.
POST returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/x-www-form-urlencoded
JSON returns data through query string parameters on a POST to the given URL, with a full set of data in a JSON-encoded structure in the body. The request will have a header of application/json

For information on data encoding formats, see the Data Handling section.

url_username, url_password

Callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

Data Handling

Each type of method provides a different way of transmitting data associated with the callback. A full listing of available data and an explanation of their values is provided with the specific callback's documentation.

GET

If the method is GET, FoneStorm will apply token substitution to the value provided in url.

Example

If the url for a messages/receive_notify callback is https://my.example.com/notify.php?direction=((direction)), the ((direction)) token will be replaced with the direction of the call. The actual callback URL that is executed would be something like https://my.example.com/notify.php?direction=OUTBOUND

Parameter	Type	Description
account_code	string	Account billed for call
direction	string	`OUTBOUND` or `INBOUND`
status	string	`BEGIN` or `END`
from	string	Caller id.
to	string	Call destination.
type	string	`FAX`
disposition	string	One of the following: `ANSWERED` `NO_ANSWER` `REJECTED` `BUSY` `CANCEL` `INVALID` `FAILED` `FAILED:###`
billable_seconds	number	Number of seconds billable for the call
id	string	Unique identifier for the call.

POST

If the method is POST, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON.

Example

If the url for the callback is https://my.example.com/notify.php, the body for the callback request will contain a string like {"to":"3215551212","from":"3215551111","account_code":"2005559999","id":"0c4055acc5cc2736d818c96f4421b2f5","billable_seconds":"10","direction":"OUTBOUND","status":"END","type":"FAX","disposition":"ANSWERED"}.

JSON

If the method is JSON, FoneStorm will apply token substitutions to url, as with GET, but additionally it will provide the full set of available values in the body of the request, as JSON Object.

Example

If the url for the callback is https://my.example.com/notify.php, the body for the callback request will contain a JSON Object like

{ 
    "to": "3215551212",
    "from": "3215551111",
    "account_code" :"2005559999",
    "id": "0c4055acc5cc2736d818c96f4421b2f5",
    "billable_seconds": 10,
    "direction": "OUTBOUND",
    "status": "END",
    "type": "FAX",
    "disposition": "ANSWERED"
}

url_username, url_password

Callbacks support optional HTTP Basic authentication. If the url_username and url_password parameters are provided, the corresponding authentication headers will be included in callback execution.

For more information, see Callbacks / Web Hooks.

The structure for fax_options is shown below.

{
    receive_notify: {
        type:
        url:
        method:
        url_username:
        url_password:
        email:
    }
    send_notify: {
        type:
        url:
        method:
        url_username:
        url_password:
        email:      
    }
}

Response Properties

Property	Type	Description
fonenumber	object	FoneNumber

200Success

400Bad Request

401Unauthorized

404Not Found

defaultError