Update FoneNumber

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:

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.

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

• 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.

• 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

• 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

• 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