Create service

POST /v1/Services

A Messaging Service resource to create, fetch, update, delete or add/remove senders from Messaging Services.

Body

  • AreaCodeGeomatch boolean

    Whether to enable Area Code Geomatch on the Service Instance.

  • FallbackMethod string(http-method)

    The HTTP method we should use to call fallback_url. Can be: GET or POST.

    Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

  • FallbackToLongCode boolean

    Whether to enable Fallback to Long Code for messages sent through the Service instance.

  • FallbackUrl string(uri)

    The URL that we call using fallback_method if an error occurs while retrieving or executing the TwiML from the Inbound Request URL. If the use_inbound_webhook_on_number field is enabled then the webhook url defined on the phone number will override the fallback_url defined for the Messaging Service.

  • FriendlyName string Required

    A descriptive string that you create to describe the resource. It can be up to 64 characters long.

  • InboundMethod string(http-method)

    The HTTP method we should use to call inbound_request_url. Can be GET or POST and the default is POST.

    Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

  • InboundRequestUrl string(uri)

    The URL we call using inbound_method when a message is received by any phone number or short code in the Service. When this property is null, receiving inbound messages is disabled. All messages sent to the Twilio phone number or short code will not be logged and received on the Account. If the use_inbound_webhook_on_number field is enabled then the webhook url defined on the phone number will override the inbound_request_url defined for the Messaging Service.

  • MmsConverter boolean

    Whether to enable the MMS Converter for messages sent through the Service instance.

  • ScanMessageContent string

    Reserved.

    Values are inherit, enable, or disable.

  • SmartEncoding boolean

    Whether to enable Smart Encoding for messages sent through the Service instance.

  • StatusCallback string(uri)

    The URL we should call to pass status updates about message delivery.

  • StickySender boolean

    Whether to enable Sticky Sender on the Service instance.

  • SynchronousValidation boolean

    Reserved.

  • UseInboundWebhookOnNumber boolean

    A boolean value that indicates either the webhook url configured on the phone number will be used or inbound_request_url/fallback_url url will be called when a message is received from the phone number. If this field is enabled then the webhook url defined on the phone number will override the inbound_request_url/fallback_url defined for the Messaging Service.

  • Usecase string

    A string that describes the scenario in which the Messaging Service will be used. Examples: [notification, marketing, verification, poll ..].

  • ValidityPeriod integer

    How long, in seconds, messages sent from the Service are valid. Can be an integer from 1 to 14,400.

Responses

  • 201

    Created

    Hide response attributes Show response attributes object
    • account_sid string | null

      The SID of the Account that created the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • area_code_geomatch boolean | null

      Whether to enable Area Code Geomatch on the Service Instance

    • date_created string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was created

    • date_updated string(date-time) | null

      The ISO 8601 date and time in GMT when the resource was last updated

    • fallback_method string(http-method) | null

      The HTTP method we use to call fallback_url

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • fallback_to_long_code boolean | null

      Whether to enable Fallback to Long Code for messages sent through the Service instance

    • fallback_url string(uri) | null

      The URL that we call using fallback_method if an error occurs while retrieving or executing the TwiML from the Inbound Request URL. This field will be overridden if the use_inbound_webhook_on_number field is enabled.

    • friendly_name string | null

      The string that you assigned to describe the resource

    • inbound_method string(http-method) | null

      The HTTP method we use to call inbound_request_url

      Values are HEAD, GET, POST, PATCH, PUT, or DELETE.

    • inbound_request_url string(uri) | null

      The URL we call using inbound_method when a message is received by any phone number or short code in the Service. This field will be overridden if the use_inbound_webhook_on_number field is enabled.

    • links object(uri-map) | null

      The absolute URLs of related resources

    • mms_converter boolean | null

      Whether to enable the MMS Converter for messages sent through the Service instance

    • scan_message_content string | null

      Reserved

      Values are inherit, enable, or disable.

    • sid string | null

      The unique string that identifies the resource

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^MG[0-9a-fA-F]{32}$.

    • smart_encoding boolean | null

      Whether to enable Encoding for messages sent through the Service instance

    • status_callback string(uri) | null

      The URL we call to pass status updates about message delivery

    • sticky_sender boolean | null

      Whether to enable Sticky Sender on the Service instance

    • synchronous_validation boolean | null

      Reserved

    • url string(uri) | null

      The absolute URL of the Service resource

    • us_app_to_person_registered boolean | null

      Whether US A2P campaign is registered for this Service.

    • use_inbound_webhook_on_number boolean | null

      If enabled, the webhook url configured on the phone number will be used and will override the inbound_request_url/fallback_url url called when an inbound message is received.

    • usecase string | null

      A string describing the scenario in which the Messaging Service will be used

    • validity_period integer | null

      How long, in seconds, messages sent from the Service are valid
POST /v1/Services 
curl \
 -X POST https://messaging.twilio.com/v1/Services \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AreaCodeGeomatch=true&FallbackMethod=HEAD&FallbackToLongCode=true&FallbackUrl=https%3A%2F%2Fexample.com&FriendlyName=string&InboundMethod=HEAD&InboundRequestUrl=https%3A%2F%2Fexample.com&MmsConverter=true&ScanMessageContent=inherit&SmartEncoding=true&StatusCallback=https%3A%2F%2Fexample.com&StickySender=true&SynchronousValidation=true&UseInboundWebhookOnNumber=true&Usecase=string&ValidityPeriod=42'
Request example 
{
  "AreaCodeGeomatch": true,
  "FallbackMethod": "HEAD",
  "FallbackToLongCode": true,
  "FallbackUrl": "https://example.com",
  "FriendlyName": "string",
  "InboundMethod": "HEAD",
  "InboundRequestUrl": "https://example.com",
  "MmsConverter": true,
  "ScanMessageContent": "inherit",
  "SmartEncoding": true,
  "StatusCallback": "https://example.com",
  "StickySender": true,
  "SynchronousValidation": true,
  "UseInboundWebhookOnNumber": true,
  "Usecase": "string",
  "ValidityPeriod": 42
}
Request examples 
{
  "AreaCodeGeomatch": true,
  "FallbackMethod": "HEAD",
  "FallbackToLongCode": true,
  "FallbackUrl": "https://example.com",
  "FriendlyName": "string",
  "InboundMethod": "HEAD",
  "InboundRequestUrl": "https://example.com",
  "MmsConverter": true,
  "ScanMessageContent": "inherit",
  "SmartEncoding": true,
  "StatusCallback": "https://example.com",
  "StickySender": true,
  "SynchronousValidation": true,
  "UseInboundWebhookOnNumber": true,
  "Usecase": "string",
  "ValidityPeriod": 42
}
Response examples (201) 
{
  "account_sid": "string",
  "area_code_geomatch": true,
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "fallback_method": "HEAD",
  "fallback_to_long_code": true,
  "fallback_url": "https://example.com",
  "friendly_name": "string",
  "inbound_method": "HEAD",
  "inbound_request_url": "https://example.com",
  "links": {},
  "mms_converter": true,
  "scan_message_content": "inherit",
  "sid": "string",
  "smart_encoding": true,
  "status_callback": "https://example.com",
  "sticky_sender": true,
  "synchronous_validation": true,
  "url": "https://example.com",
  "us_app_to_person_registered": true,
  "use_inbound_webhook_on_number": true,
  "usecase": "string",
  "validity_period": 42
}
Response examples (201) 
{
  "account_sid": "string",
  "area_code_geomatch": true,
  "date_created": "2024-05-04T09:42:00+00:00",
  "date_updated": "2024-05-04T09:42:00+00:00",
  "fallback_method": "HEAD",
  "fallback_to_long_code": true,
  "fallback_url": "https://example.com",
  "friendly_name": "string",
  "inbound_method": "HEAD",
  "inbound_request_url": "https://example.com",
  "links": {},
  "mms_converter": true,
  "scan_message_content": "inherit",
  "sid": "string",
  "smart_encoding": true,
  "status_callback": "https://example.com",
  "sticky_sender": true,
  "synchronous_validation": true,
  "url": "https://example.com",
  "us_app_to_person_registered": true,
  "use_inbound_webhook_on_number": true,
  "usecase": "string",
  "validity_period": 42
}