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

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/enterprises/dir.rb,
lib/telnyx/resources/enterprises/dir/comments.rb,
lib/telnyx/resources/enterprises/dir/phone_numbers.rb,
lib/telnyx/resources/enterprises/dir/phone_number_batches.rb

Overview

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

Defined Under Namespace

Classes: Comments, PhoneNumberBatches, PhoneNumbers

Instance Attribute Summary collapse

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:



152
153
154
155
156
157
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 152

def initialize(client:)
  @client = client
  @comments = Telnyx::Resources::Enterprises::Dir::Comments.new(client: client)
  @phone_number_batches = Telnyx::Resources::Enterprises::Dir::PhoneNumberBatches.new(client: client)
  @phone_numbers = Telnyx::Resources::Enterprises::Dir::PhoneNumbers.new(client: client)
end

Instance Attribute Details

#comments ⇒ Telnyx::Resources::Enterprises::Dir::Comments (readonly)

Returns:



10
11
12
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 10

def comments
  @comments
end

#phone_number_batches ⇒ Telnyx::Resources::Enterprises::Dir::PhoneNumberBatches (readonly)

Returns:



13
14
15
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 13

def phone_number_batches
  @phone_number_batches
end

#phone_numbers ⇒ Telnyx::Resources::Enterprises::Dir::PhoneNumbers (readonly)

Returns:



16
17
18
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 16

def phone_numbers
  @phone_numbers
end

Instance Method Details

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

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.

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

  • call_reasons (Array<String>) —

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

  • documents (Array<Telnyx::Models::Enterprises::DirCreateParams::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:



76
77
78
79
80
81
82
83
84
85
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 76

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::Models::Enterprises::DirCreateResponse,
    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::Enterprises::DirListResponse>

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`, `page`, max 250). Supports `filter[]` query params: `filter`, `filter[contains]`, `filter[contains]`, plus the renewal-window filters `filter[gte]` / `filter[lte]` and the convenience `filter` (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::Enterprises::DirListParams::FilterStatus) —

    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:



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/telnyx/resources/enterprises/dir.rb', line 127

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::Models::Enterprises::DirListResponse,
    options: options
  )
end