Create service

POST /v1/Services

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

application/x-www-form-urlencoded

Body

  • FriendlyName string Required

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

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

  • 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 GET or POST.

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

  • FallbackMethod string(http-method)

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

    Values are GET or POST.

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

  • MmsConverter boolean

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

  • SmartEncoding boolean

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

  • ScanMessageContent string

    Reserved.

    Values are inherit, enable, or disable.

  • FallbackToLongCode boolean

    [OBSOLETE] Former feature used to fallback to long code sender after certain short code message failures.

  • AreaCodeGeomatch boolean

    Whether to enable Area Code Geomatch on the Service Instance.

  • ValidityPeriod integer

    How long, in seconds, messages sent from the Service are valid. Can be an integer from 1 to 36,000. Default value is 36,000.

  • SynchronousValidation boolean

    Reserved.

  • Usecase string

    A string that describes the scenario in which the Messaging Service will be used. Possible values are notifications, marketing, verification, discussion, poll, undeclared.

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

Responses

  • 201 application/json

    Created

    Hide headers attributes Show headers attributes
    • Access-Control-Allow-Origin string

      Specify the origin(s) allowed to access the resource

    • Access-Control-Allow-Methods string

      Specify the HTTP methods allowed when accessing the resource

    • Access-Control-Allow-Headers string

      Specify the headers allowed when accessing the resource

    • Access-Control-Allow-Credentials boolean

      Indicates whether the browser should include credentials

    • Access-Control-Expose-Headers string

      Headers exposed to the client

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

      The unique string that we created to identify the Service resource.

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

    • account_sid string | null

      The SID of the Account that created the Service resource.

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

    • friendly_name string | null

      The string that you assigned to describe the resource.

    • date_created string(date-time) | null

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

    • date_updated string(date-time) | null

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

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

    • inbound_method string(http-method) | null

      The HTTP method we use to call inbound_request_url. Can be GET or POST.

      Values are GET or POST.

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

    • fallback_method string(http-method) | null

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

      Values are GET or POST.

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

    • mms_converter boolean | null

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

    • smart_encoding boolean | null

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

    • scan_message_content string

      Reserved.

      Values are inherit, enable, or disable.

    • fallback_to_long_code boolean | null

      [OBSOLETE] Former feature used to fallback to long code sender after certain short code message failures.

    • area_code_geomatch boolean | null

      Whether to enable Area Code Geomatch on the Service Instance.

    • synchronous_validation boolean | null

      Reserved.

    • validity_period integer

      How long, in seconds, messages sent from the Service are valid. Can be an integer from 1 to 36,000. Default value is 36,000.

      Default value is 0.

    • url string(uri) | null

      The absolute URL of the Service resource.

    • usecase string | null

      A string that describes the scenario in which the Messaging Service will be used. Possible values are notifications, marketing, verification, discussion, poll, undeclared.

    • us_app_to_person_registered boolean | null

      Whether US A2P campaign is registered for this Service.

    • use_inbound_webhook_on_number boolean | null

      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.

POST /v1/Services
curl \
 --request POST 'https://messaging.twilio.com/v1/Services' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'Usecase=marketing&FallbackUrl=https%3A%2F%2Fwww.example.com&FriendlyName=My+Service%21&MmsConverter=true&StickySender=true&InboundMethod=POST&SmartEncoding=false&FallbackMethod=GET&StatusCallback=https%3A%2F%2Fwww.example.com&ValidityPeriod=600&AreaCodeGeomatch=true&InboundRequestUrl=https%3A%2F%2Fwww.example.com&FallbackToLongCode=true&ScanMessageContent=inherit&SynchronousValidation=true&UseInboundWebhookOnNumber=true'
Request example
{"Usecase"=>"marketing", "FallbackUrl"=>"https://www.example.com", "FriendlyName"=>"My Service!", "MmsConverter"=>true, "StickySender"=>true, "InboundMethod"=>"POST", "SmartEncoding"=>false, "FallbackMethod"=>"GET", "StatusCallback"=>"https://www.example.com", "ValidityPeriod"=>600, "AreaCodeGeomatch"=>true, "InboundRequestUrl"=>"https://www.example.com", "FallbackToLongCode"=>true, "ScanMessageContent"=>"inherit", "SynchronousValidation"=>true, "UseInboundWebhookOnNumber"=>true}
Response examples (201)
{
  "sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "links": {
    "messages": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages",
    "short_codes": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ShortCodes",
    "alpha_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/AlphaSenders",
    "phone_numbers": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/PhoneNumbers",
    "channel_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/ChannelSenders",
    "us_app_to_person": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p",
    "destination_alpha_senders": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/DestinationAlphaSenders",
    "us_app_to_person_usecases": "https://messaging.twilio.com/v1/Services/MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Compliance/Usa2p/Usecases"
  },
  "usecase": "marketing",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:12:31Z",
  "date_updated": "2015-07-30T20:12:33Z",
  "fallback_url": "https://www.example.com",
  "friendly_name": "My Service!",
  "mms_converter": true,
  "sticky_sender": true,
  "inbound_method": "POST",
  "smart_encoding": false,
  "fallback_method": "GET",
  "sending_windows": [],
  "status_callback": "https://www.example.com",
  "validity_period": 600,
  "area_code_geomatch": true,
  "inbound_request_url": "https://www.example.com/",
  "scan_message_content": "inherit",
  "fallback_to_long_code": true,
  "synchronous_validation": true,
  "us_app_to_person_registered": false,
  "use_inbound_webhook_on_number": true
}