Class: Telnyx::Resources::Enterprises::Dir

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/enterprises/dir.rb,
sig/telnyx/resources/enterprises/dir.rbs

Overview

A Display Identity Record (DIR) is the verified calling identity (display name, logo, call reasons) shown to recipients on outbound calls.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Dir

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Dir.

Parameters:



143
144
145
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 143

def initialize(client:)
  @client = client
end

Instance Method Details

#create(enterprise_id, authorizer_email:, authorizer_name:, call_reasons:, certify_brand_is_accurate:, certify_ip_ownership:, certify_no_shaft_content:, display_name:, documents: nil, logo_url: nil, reselling: nil, request_options: {}) ⇒ Telnyx::Models::DirWrapped

Some parameter documentations has been truncated, see Models::Enterprises::DirCreateParams for more details.

Create a new DIR under the given enterprise. The DIR starts in draft status; it must be submitted (POST .../submit) and approved by Telnyx before any phone number can be attached.

Field rules

  • display_name: 1–35 characters, no emoji or whitespace-only strings; this is the name shown to recipients.
  • call_reasons: 1–10 strings, each ≤64 characters; describe why your business calls customers (e.g. 'Appointment reminders', 'Billing inquiries'). Validate the wording against POST /call_reasons/validate.
  • logo_url: HTTPS URL (max 128 chars) to a 256×256 BMP (max 1 MB). The image is downloaded and hashed at submission time.
  • documents: up to 20 entries; each document_id must be obtained by uploading the file via the Telnyx Documents API first. Within one DIR a document_id may only appear once.
  • certify_brand_is_accurate, certify_no_shaft_content, certify_ip_ownership MUST all be true.

Failure modes

  • 422 - validation error; errors[].source.pointer names the offending field.
  • 403 - Branded Calling not activated on this enterprise (see POST /enterprises/{id}/branded_calling).
  • 404 - enterprise does not exist or does not belong to your account.

Parameters:

  • enterprise_id (String) —

    The enterprise id. Lowercase UUID.

  • authorizer_email (String) —

    Contact email of the authorizer. Telnyx may send verification or infringement-no

  • authorizer_name (String) —

    Name of the person at your enterprise who is authorizing this DIR registration.

  • call_reasons (Array<String>) —

    1–10 reasons your business calls customers. Validate phrasing against `POST /cal

  • certify_brand_is_accurate (Boolean, Telnyx::Models::Enterprises::DirCreateParams::CertifyBrandIsAccurate) —

    Must be true.

  • certify_ip_ownership (Boolean, Telnyx::Models::Enterprises::DirCreateParams::CertifyIPOwnership) —

    Must be true. Confirms ownership of any logos/trademarks shown.

  • certify_no_shaft_content (Boolean, Telnyx::Models::Enterprises::DirCreateParams::CertifyNoShaftContent) —

    Must be true. Confirms this DIR is not used for SHAFT content (Sex, Hate, Alco

  • display_name (String) —

    Name shown to call recipients. No emoji; not whitespace-only.

  • documents (Array<Telnyx::Models::Document>) —

    Supporting documents. Each document_id may appear at most once on a DIR.

  • logo_url (String) —

    Publicly accessible HTTPS URL (max 128 chars) to a 256x256 BMP logo (max 1 MB).

  • reselling (Boolean) —

    Set to true if your organization places calls on behalf of other enterprises (BP

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



67
68
69
70
71
72
73
74
75
76
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 67

def create(enterprise_id, params)
  parsed, options = Telnyx::Enterprises::DirCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["enterprises/%1$s/dir", enterprise_id],
    body: parsed,
    model: Telnyx::DirWrapped,
    options: options
  )
end

#list(enterprise_id, filter_call_reason_contains: nil, filter_display_name_contains: nil, filter_expiring_at_gte: nil, filter_expiring_at_lte: nil, filter_expiring_within_days: nil, filter_status: nil, page_number: nil, page_size: nil, sort: nil, request_options: {}) ⇒ Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::DirAPI>

Some parameter documentations has been truncated, see Models::Enterprises::DirListParams for more details.

Return the DIRs (Display Identity Records) belonging to a single enterprise. Pagination is JSON:API style (page[number], page[size], max 250). Supports filter[] query params: filter[status], filter[display_name][contains], filter[call_reason][contains], plus the renewal-window filters filter[expiring_at][gte] / filter[expiring_at][lte] and the convenience filter[expiring_within_days] (mutually exclusive with the explicit gte/lte form). Sortable by created_at, updated_at, display_name, status, submitted_at, verified_at, expiring_at (prefix - for descending; default -created_at).

Parameters:

  • enterprise_id (String) —

    The enterprise id. Lowercase UUID.

  • filter_call_reason_contains (String) —

    Case-insensitive partial match on call reason.

  • filter_display_name_contains (String) —

    Case-insensitive partial match on display name.

  • filter_expiring_at_gte (Time) —

    Return only DIRs whose expiring_at is at or after this ISO-8601 timestamp.

  • filter_expiring_at_lte (Time) —

    Return only DIRs whose expiring_at is at or before this ISO-8601 timestamp.

  • filter_expiring_within_days (Integer) —

    Convenience: returns DIRs whose expiring_at falls within the next N days (1–36

  • filter_status (Symbol, Telnyx::Models::DirStatus) —

    Filter by DIR status.

  • page_number (Integer) —

    1-based page number. Out-of-range values return an empty page with correct meta.

  • page_size (Integer) —

    Items per page. Maximum 250; values above are clamped to 250.

  • sort (Symbol, Telnyx::Models::Enterprises::DirListParams::Sort) —

    Sort field. Allowed: created_at, updated_at, display_name, status, `subm

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 118

def list(enterprise_id, params = {})
  parsed, options = Telnyx::Enterprises::DirListParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["enterprises/%1$s/dir", enterprise_id],
    query: query.transform_keys(
      filter_call_reason_contains: "filter[call_reason][contains]",
      filter_display_name_contains: "filter[display_name][contains]",
      filter_expiring_at_gte: "filter[expiring_at][gte]",
      filter_expiring_at_lte: "filter[expiring_at][lte]",
      filter_expiring_within_days: "filter[expiring_within_days]",
      filter_status: "filter[status]",
      page_number: "page[number]",
      page_size: "page[size]"
    ),
    page: Telnyx::Internal::DefaultFlatPagination,
    model: Telnyx::DirAPI,
    options: options
  )
end