# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Twilio - Messaging Link Shortening API
  version: 1.0.0
extends: openapi/twilio-linkshortening-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/v1/LinkShortening/Domains/{DomainSid}/Certificate'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the TLS certificate on a short-link domain
      effect: read
      questions:
      - Is the TLS certificate on my branded link-shortening domain valid and uploaded?
      - Can I see which certificate is currently attached to a short-link domain?
      instructions:
      - text: Show the TLS certificate for short-link domain {domain}.
        slots:
          domain: path.DomainSid
      - text: Check the certificate status on domain {domain}.
        slots:
          domain: path.DomainSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/Domains/{DomainSid}/Certificate'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a TLS certificate for a short-link domain
      effect: write
      questions:
      - How do I upload my own TLS certificate so shortened links work over HTTPS?
      - What format does the certificate and private key need to be in for a branded link domain?
      instructions:
      - text: Upload PEM certificate {cert} to short-link domain {domain}.
        slots:
          cert: requestBody.TlsCert
          domain: path.DomainSid
      - text: Replace the expiring certificate on domain {domain} with {cert}.
        slots:
          domain: path.DomainSid
          cert: requestBody.TlsCert
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/Domains/{DomainSid}/Certificate'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove the TLS certificate from a short-link domain
      effect: destructive
      questions:
      - Can I remove the certificate I uploaded for a link-shortening domain?
      - What happens to HTTPS short links if I delete a domain's certificate?
      instructions:
      - text: Delete the TLS certificate on short-link domain {domain}.
        slots:
          domain: path.DomainSid
      - text: Remove the uploaded cert from domain {domain}.
        slots:
          domain: path.DomainSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/Domains/{DomainSid}/Config'].get
  update:
    x-apievangelist-phrasing:
      intent: View a short-link domain's configuration
      effect: read
      questions:
      - Where do unmatched visits to my short-link domain get redirected?
      - Which webhook receives click events for a branded link domain?
      instructions:
      - text: Show the configuration of short-link domain {domain}.
        slots:
          domain: path.DomainSid
      - text: Get the fallback and click-callback URLs set on domain {domain}.
        slots:
          domain: path.DomainSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/Domains/{DomainSid}/Config'].post
  update:
    x-apievangelist-phrasing:
      intent: Configure fallback, click webhook and HTTPS for a domain
      effect: write
      questions:
      - How do I get a webhook every time a recipient clicks a shortened link?
      - Can I send shortened links without the https:// prefix?
      - Should messages still go out if link shortening fails, and where do I set that?
      instructions:
      - text: Send click events for domain {domain} to {callback}.
        slots:
          domain: path.DomainSid
          callback: requestBody.CallbackUrl
      - text: Redirect unmatched short links on {domain} to {fallback}.
        slots:
          domain: path.DomainSid
          fallback: requestBody.FallbackUrl
      - text: Set continue-on-failure to {continue} for short-link domain {domain}.
        slots:
          continue: requestBody.ContinueOnFailure
          domain: path.DomainSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/MessagingService/{MessagingServiceSid}/DomainConfig'].get
  update:
    x-apievangelist-phrasing:
      intent: View domain config through a Messaging Service
      effect: read
      questions:
      - What link-shortening domain settings apply to a given Messaging Service?
      - Can I look up the short-link config starting from the Messaging Service instead of the domain?
      instructions:
      - text: Show the link-shortening domain config used by Messaging Service {service}.
        slots:
          service: path.MessagingServiceSid
      - text: Get the fallback and callback settings that apply to service {service}.
        slots:
          service: path.MessagingServiceSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/Domains/{DomainSid}/MessagingServices/{MessagingServiceSid}'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a short-link domain to a Messaging Service
      effect: write
      questions:
      - How do I make a Messaging Service shorten links with my branded domain?
      - Can one short-link domain be linked to a specific Messaging Service?
      instructions:
      - text: Associate short-link domain {domain} with Messaging Service {service}.
        slots:
          domain: path.DomainSid
          service: path.MessagingServiceSid
      - text: Turn on branded link shortening for service {service} using domain {domain}.
        slots:
          service: path.MessagingServiceSid
          domain: path.DomainSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/Domains/{DomainSid}/MessagingServices/{MessagingServiceSid}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Detach a short-link domain from a Messaging Service
      effect: destructive
      questions:
      - How do I stop a Messaging Service from using my branded short-link domain?
      - Can I unlink a domain from one service without deleting the domain?
      instructions:
      - text: Dissociate domain {domain} from Messaging Service {service}.
        slots:
          domain: path.DomainSid
          service: path.MessagingServiceSid
      - text: Stop service {service} from shortening links with domain {domain}.
        slots:
          service: path.MessagingServiceSid
          domain: path.DomainSid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v1/LinkShortening/MessagingServices/{MessagingServiceSid}/Domain'].get
  update:
    x-apievangelist-phrasing:
      intent: Find which domain a Messaging Service shortens with
      effect: read
      questions:
      - Which short-link domain is my Messaging Service associated with?
      - Is any branded link domain attached to this Messaging Service yet?
      instructions:
      - text: Tell me which short-link domain is associated with Messaging Service {service}.
        slots:
          service: path.MessagingServiceSid
      - text: Look up the domain association for service {service}.
        slots:
          service: path.MessagingServiceSid
      method: generated
      generated: '2026-09-26'